From d72326d0e6a906e8e8368f17237c628ea7829414 Mon Sep 17 00:00:00 2001 From: Max Stepanov Date: Mon, 27 Feb 2012 18:35:28 -0800 Subject: [PATCH] modules API docs --- iphone/AppledocSettings.plist | 65 ++++++ iphone/Classes/ImageLoader.h | 119 +++++++++++ iphone/Classes/OperationQueue.h | 19 +- iphone/Classes/Ti2DMatrix.h | 17 ++ iphone/Classes/TiAction.h | 20 +- iphone/Classes/TiAnimation.h | 53 +++++ iphone/Classes/TiApp.h | 115 ++++++++++- iphone/Classes/TiBase.h | 6 +- iphone/Classes/TiBlob.h | 94 ++++++++- iphone/Classes/TiBuffer.h | 14 ++ iphone/Classes/TiColor.h | 33 ++- iphone/Classes/TiComplexValue.h | 25 ++- iphone/Classes/TiDimension.h | 3 + iphone/Classes/TiFile.h | 42 +++- iphone/Classes/TiLayoutQueue.h | 12 ++ iphone/Classes/TiLocale.h | 26 +++ iphone/Classes/TiModule.h | 49 +++++ iphone/Classes/TiPoint.h | 26 ++- iphone/Classes/TiProxy.h | 77 +++++++ iphone/Classes/TiRange.h | 14 ++ iphone/Classes/TiRect.h | 27 +++ iphone/Classes/TiRootController.h | 69 +++++++ iphone/Classes/TiRootViewController.h | 57 ++++++ iphone/Classes/TiTab.h | 17 ++ iphone/Classes/TiTabController.h | 6 + iphone/Classes/TiTabGroup.h | 7 + iphone/Classes/TiToolbar.h | 7 + iphone/Classes/TiToolbarButton.h | 17 ++ iphone/Classes/TiUIView.h | 113 +++++++++++ iphone/Classes/TiUtils.h | 29 ++- iphone/Classes/TiViewController.h | 60 +++++- iphone/Classes/TiViewProxy.h | 276 ++++++++++++++++++++++++++ iphone/Classes/TiWindowProxy.h | 61 +++++- iphone/Classes/WebFont.h | 66 ++++++ iphone/Classes/Webcolor.h | 22 ++ 35 files changed, 1619 insertions(+), 44 deletions(-) create mode 100644 iphone/AppledocSettings.plist diff --git a/iphone/AppledocSettings.plist b/iphone/AppledocSettings.plist new file mode 100644 index 00000000000..1d0c7cceb30 --- /dev/null +++ b/iphone/AppledocSettings.plist @@ -0,0 +1,65 @@ + + + + + --project-company + Apcelerator, Inc. + --company-id + com.appcelerator + --project-name + Titanium Modules API + --create-docset + + --install-docset + + --clean-output + + --search-undocumented-doc + + --repeat-first-par + + --explicit-crossref + + --verbose + 4 + --logformat + 1 + --input + + Classes/TiRootViewController.h + Classes/TiApp.h + Classes/TiFile.h + Classes/TiUIView.h + Classes/TiViewProxy.h + Classes/TiModule.h + Classes/TiWindowProxy.h + Classes/TiViewController.h + Classes/TiProxy.h + Classes/TiTab.h + Classes/TiBlob.h + Classes/TiBase.h + Classes/TiAnimation.h + Classes/TiAction.h + Classes/TiToolbar.h + Classes/TiTabGroup.h + Classes/TiToolbarButton.h + Classes/TiTabController.h + Classes/TiRootController.h + Classes/TiLocale.h + Classes/TiBuffer.h + Classes/WebFont.h + Classes/Webcolor.h + Classes/TiRect.h + Classes/TiRange.h + Classes/TiPoint.h + Classes/TiComplexValue.h + Classes/TiColor.h + Classes/Ti2DMatrix.h + Classes/ImageLoader.h + Classes/TiLayoutQueue.h + Classes/TiDimension.h + Classes/OperationQueue.h + Classes/TiUtils.h + + + diff --git a/iphone/Classes/ImageLoader.h b/iphone/Classes/ImageLoader.h index ae4a0aabb36..cbe3509d7b7 100644 --- a/iphone/Classes/ImageLoader.h +++ b/iphone/Classes/ImageLoader.h @@ -20,14 +20,39 @@ typedef enum { @class ImageLoaderRequest; +/** + Protocol for image loader delegate. + */ @protocol ImageLoaderDelegate @required + +/** + Tells the delegate that the image load request succeeded. + @param request The load request. + @param image The loaded image. + */ -(void)imageLoadSuccess:(ImageLoaderRequest*)request image:(UIImage*)image; + +/** + Tells the delegate that the image load request failed. + @param request The load request. + @param error The error. + */ -(void)imageLoadFailed:(ImageLoaderRequest*)request error:(NSError*)error; + @optional + +/** + Tells the delegate that the image load request has been cancelled. + @param request The load request. + */ -(void)imageLoadCancelled:(ImageLoaderRequest*)request; + @end +/** + Image loader request class. + */ @interface ImageLoaderRequest : NSObject { @private ASIHTTPRequest *request; @@ -41,18 +66,53 @@ typedef enum { @property(nonatomic,readwrite,retain) ASIHTTPRequest* request; +/** + Returns if the request has completed. + @return _YES_ if the request has completed, _NO_ otherwise. + */ @property(nonatomic,readwrite,assign) BOOL completed; + +/** + Returns loaded image size. + @return The loaded image size + */ @property(nonatomic,readwrite,assign) CGSize imageSize; + +/** + Returns the request delegate. + @return The request delegate. + */ @property(nonatomic,readonly) NSObject* delegate; +/** + Cancells the request. + */ -(void)cancel; + +/** + Returns is the image load request was cancelled. + @return _YES_ if request was cancelled, _NO_ otherwise. + */ -(BOOL)cancelled; + +/** + Returns request additional properties. + @return The dictionary of properties. + */ -(NSDictionary*)userInfo; + +/** + Returns the request URL. + @return The image URL. + */ -(NSURL*)url; @end +/** + The image loader. + */ @interface ImageLoader : NSObject { @private NSCache *cache; @@ -61,22 +121,81 @@ typedef enum { NSRecursiveLock* lock; } +/** + Returns the shared instance of image loader. + @return The shared instance. + */ +(ImageLoader*)sharedLoader; +/** + Tells the loader to load remote image from URL. + @param url The image URL + @return The loaded image. + */ -(UIImage *)loadRemote:(NSURL*)url; + +/** + Tells the loader to return previously loaded image with URL. + @param url The image URL + @return The loaded image. + */ -(UIImage *)loadImmediateImage:(NSURL *)url; + +/** + Tells the loader to return previously loaded image with URL and size. + @param url The image URL + @param imageSize The required image size. + @return The loaded image. + */ -(UIImage *)loadImmediateImage:(NSURL *)url withSize:(CGSize)imageSize; + +/** + Tells the loader to return previously loaded stretchable image with URL. + @param url The image URL + @return The loaded image. + */ -(UIImage *)loadImmediateStretchableImage:(NSURL *)url; + +/** + Tells the loader to return previously loaded stretchable image with URL for dimensions. + @param url The image URL + @param left The left dimension + @param top The top dimension. + @return The loaded image. + */ -(UIImage *)loadImmediateStretchableImage:(NSURL *)url withLeftCap:(TiDimension)left topCap:(TiDimension)top; +/** + Returns the full image size. + @param url The image URL + @return The image size. + */ -(CGSize)fullImageSize:(NSURL *)url; +/** + Tells the loader to load image from URL with delegate. + @param url The image URL. + @param delegate The loader delegate. + @param userInfo The additional properties to be assigned to the request. + @return The image load request. + */ -(ImageLoaderRequest*)loadImage:(NSURL*)url delegate:(NSObject*)delegate userInfo:(NSDictionary*)userInfo; +/** + Tells the image loader to suspend it's activities. + */ -(void)suspend; + +/** + Tells teh image loader to resume it's activities. + */ -(void)resume; + +/** + Tells the image loader to cancel all activities. + */ -(void)cancel; @end diff --git a/iphone/Classes/OperationQueue.h b/iphone/Classes/OperationQueue.h index 5ede372a4d1..906333b4b26 100644 --- a/iphone/Classes/OperationQueue.h +++ b/iphone/Classes/OperationQueue.h @@ -12,17 +12,28 @@ * that can be used to handle background jobs and after the jobs complete * can call a callback either on or off the main UI thread. */ - @interface OperationQueue : NSObject { NSOperationQueue *queue; } +/** + Returns shared instance. + @return The shared instance. + */ +(OperationQueue*)sharedQueue; /** - * queue an operation that targets selector on target - * invoke after (if not nil) on when completed - * pass YES to ui to invoke after on UI main thread + Queues an operation. + + Queues an operation that targets selector on target + invoke after (if not nil) on when completed + pass YES to ui to invoke after on UI main thread + @param selector The selector. + @param target The target. + @param arg The argument + @param after The after selector. + @param on The after target. + @param ui The flag to invoke after on UI thread. */ -(void)queue:(SEL)selector target:(id)target arg:(id)arg after:(SEL)after on:(id)on ui:(BOOL)ui; diff --git a/iphone/Classes/Ti2DMatrix.h b/iphone/Classes/Ti2DMatrix.h index 691a8fa4c4f..7282807d343 100644 --- a/iphone/Classes/Ti2DMatrix.h +++ b/iphone/Classes/Ti2DMatrix.h @@ -6,15 +6,32 @@ */ #import "TiProxy.h" +/** + The proxy class for 2D matrix. + */ @interface Ti2DMatrix : TiProxy { @protected CGAffineTransform matrix; } +/** + Initializes the proxy with properties. + @param dict_ The properties dictionary. + */ -(id)initWithProperties:(NSDictionary*)dict_; + +/** + Initializes the proxy with transform matrix. + @param matrix_ The transform matrix. + */ -(id)initWithMatrix:(CGAffineTransform)matrix_; +/** + Returns transform matrix. + @return The transform matrix. + */ -(CGAffineTransform)matrix; + -(Ti2DMatrix*)translate:(id)args; -(Ti2DMatrix*)scale:(id)args; -(Ti2DMatrix*)rotate:(id)args; diff --git a/iphone/Classes/TiAction.h b/iphone/Classes/TiAction.h index 1eb752c3289..e6992f77807 100644 --- a/iphone/Classes/TiAction.h +++ b/iphone/Classes/TiAction.h @@ -7,10 +7,9 @@ #import "TiBase.h" /** - * generic action wrapper class for packaging something that you + * The generic action wrapper class for packaging something that you * want to be executed but simplier than an NSOperation */ - @interface TiAction : NSObject { @protected id target; @@ -18,11 +17,28 @@ id arg; } +/** + Initializes the action. + @param target_ The action target object. + @param selector_ The selector to perform on the target. + @param arg_ The argument to pass to the method. + */ -(id)initWithTarget:(id)target_ selector:(SEL)selector_ arg:(id)arg_; -(void)execute; +/** + Returns the target object for the action. + */ @property(nonatomic,readonly) id target; + +/** + Returns the actions's selector. + */ @property(nonatomic,readonly) SEL selector; + +/** + Returns the action's argument. + */ @property(nonatomic,readonly) id arg; diff --git a/iphone/Classes/TiAnimation.h b/iphone/Classes/TiAnimation.h index fe82f061b26..631da35abe1 100644 --- a/iphone/Classes/TiAnimation.h +++ b/iphone/Classes/TiAnimation.h @@ -13,19 +13,50 @@ @class TiViewProxy; +/** + Protocol for animation delegate. + */ @protocol TiAnimationDelegate @optional +/** + Returns if the animation should transition. + @param sender The sender of the message. + @return _YES_ if the animation should transition, _NO_ otherwise. + */ -(BOOL)animationShouldTransition:(id)sender; + +/** + Tells the delegate that the animation will start. + @param sender The sender of the message. + */ -(void)animationWillStart:(id)sender; + +/** + Tells the delegate that the animation did start. + @param sender The sender of the message. + */ -(void)animationDidStart:(id)sender; + +/** + Tells the delegate that the animation will complete. + @param sender The sender of the message. + */ -(void)animationWillComplete:(id)sender; + +/** + Tells the delegate that the animation did complete. + @param sender The sender of the message. + */ -(void)animationDidComplete:(id)sender; @end +/** + The class represents animation proxy. + */ @interface TiAnimation : TiProxy { @private NSNumber *zIndex; @@ -65,12 +96,34 @@ id transformMatrix; } +/** + Provides access to animation delegate object. + */ @property(nonatomic,assign,readwrite) NSObject *delegate; +/** + Provides access to the view being animated. + */ @property(nonatomic,readwrite,assign) UIView* animatedView; + +/** + Provides access to autoreverse view to be animated. + */ @property(nonatomic,readwrite,assign) UIView* autoreverseView; + +/** + Provides access to animation transformation matrix. + */ @property(nonatomic,readwrite,assign) id transformMatrix; + +/** + Returns autoreverse layout. + */ @property(nonatomic,readonly) LayoutConstraint autoreverseLayout; + +/** + Returns the callback for the animation. + */ @property(nonatomic,readonly) ListenerEntry* callback; // animatable properties against what is being animated diff --git a/iphone/Classes/TiApp.h b/iphone/Classes/TiApp.h index 9a970b6de46..b40d4ccc1be 100644 --- a/iphone/Classes/TiApp.h +++ b/iphone/Classes/TiApp.h @@ -24,6 +24,10 @@ TI_INLINE void waitForMemoryPanicCleared() //WARNING: This must never be run o } } +/** + TiApp represents an instance of an application. There is always only one instance per application which could be accessed through class method. + @see app + */ @interface TiApp : TiHost { UIWindow *window; @@ -58,40 +62,147 @@ TI_INLINE void waitForMemoryPanicCleared() //WARNING: This must never be run o UILocalNotification *localNotification; } +/** + Returns application primary window. + + Convenience method to access the application's primary window + */ @property (nonatomic, retain) IBOutlet UIWindow *window; + @property (nonatomic, assign) id remoteNotificationDelegate; + +/** + Returns details for the last remote notification. + + Dictionary containing details about remote notification, or _nil_. + */ @property (nonatomic, readonly) NSDictionary* remoteNotification; + +/** + Returns the application's root view controller. + */ @property (nonatomic, retain) TiRootViewController* controller; + @property (nonatomic, readonly) TiContextGroupRef contextGroup; + +/** + Returns singleton instance of TiApp application object. + */ +(TiApp*)app; -//Convenience method + +/** + Convenience method to returns root view controller for TiApp instance. + @return The application's root view controller. + @see controller + */ +(TiRootViewController*)controller; + +(TiContextGroupRef)contextGroup; -(void)attachXHRBridgeIfRequired; +/** + Returns application launch options + + The method provides access to application launch options that became available when application just launched. + @return The launch options dictionary. + */ -(NSDictionary*)launchOptions; + +/** + Returns remote UUID for the current running device. + + @return Current device UUID. + */ -(NSString*)remoteDeviceUUID; +/** + Tells application to show network activity indicator. + + Every call of startNetwork should be paired with . + @see stopNetwork + */ -(void)startNetwork; + +/** + Tells application to hide network activity indicator. + + Every call of stopNetwork should have corresponding call. + @see startNetwork + */ -(void)stopNetwork; +/** + Tells application to display modal error dialog. + + @param message Message to display + */ -(void)showModalError:(NSString*)message; +/** + Tells application to display modal view controller. + + @param controller The view controller to display. + @param animated If _YES_, animates the view controller as it’s presented; otherwise, does not. + */ -(void)showModalController:(UIViewController*)controller animated:(BOOL)animated; --(void)hideModalController:(UIViewController*)controller animated:(BOOL)animated; +/** + Tells application to hide modal view controller. + + @param controller The view controller to hide. + @param animated If _YES_, animates the view controller as it’s hidden; otherwise, does not. + */ +-(void)hideModalController:(UIViewController*)controller animated:(BOOL)animated; +/** + Returns user agent string to use for network requests. + + @return User agent string + */ -(NSString*)userAgent; + +/** + Returns unique identifier for the current application launch. + + @return Current session id. + */ -(NSString*)sessionId; -(KrollBridge*)krollBridge; -(void)beginBackgrounding; -(void)endBackgrounding; + +/** + Tells application to register background service. + + @param proxy The proxy object representing background service to register. + @see unregisterBackgroundService: + */ -(void)registerBackgroundService:(TiProxy*)proxy; + +/** + Tells application to unregister background service. + + @param proxy The proxy object representing background service to unregister. + @see registerBackgroundService: + */ -(void)unregisterBackgroundService:(TiProxy*)proxy; + +/** + Tells application that the background service has stopped. + + @param proxy The proxy object representing background service. + @see registerBackgroundService: + */ -(void)stopBackgroundService:(TiProxy*)proxy; + +/** + Returns local notification that has bees sent on the application. + + @return The last local notification + */ -(UILocalNotification*)localNotification; @end diff --git a/iphone/Classes/TiBase.h b/iphone/Classes/TiBase.h index 23fec3f8585..13b41df3302 100644 --- a/iphone/Classes/TiBase.h +++ b/iphone/Classes/TiBase.h @@ -532,7 +532,7 @@ extern NSString * const kTiLocalNotification; #include "TiThreading.h" -/* +/** * TiThreadPerformOnMainThread should replace all Titanium instances of * performSelectorOnMainThread, ESPECIALLY if wait is to be yes. That way, * exceptional-case main thread activities can process them outside of the @@ -541,7 +541,7 @@ extern NSString * const kTiLocalNotification; void TiThreadPerformOnMainThread(void (^mainBlock)(void),BOOL waitForFinish); -/* +/** * The one mixed blessing about blocks is that they retain+autorelease the * stack variables, and inside a method, that includes self. During a dealloc, * this may be dangerous. In order to make life easier for everyone, two @@ -552,7 +552,7 @@ void TiThreadPerformOnMainThread(void (^mainBlock)(void),BOOL waitForFinish); void TiThreadReleaseOnMainThread(id releasedObject,BOOL waitForFinish); void TiThreadRemoveFromSuperviewOnMainThread(UIView* view,BOOL waitForFinish); -/* +/** * Blocks sent to TiThreadPerformOnMainThread will be processed on the main * thread. Most of the time, this is done using dispatch_async or * dispatch_sync onto the main queue as needed. However, there are some cases diff --git a/iphone/Classes/TiBlob.h b/iphone/Classes/TiBlob.h index 04bce055bb0..f5dec52ca3a 100644 --- a/iphone/Classes/TiBlob.h +++ b/iphone/Classes/TiBlob.h @@ -12,7 +12,9 @@ typedef enum { TiBlobTypeData = 2 } TiBlobType; - +/** + Blob object class. + */ @interface TiBlob : TiProxy { @private TiBlobType type; @@ -22,36 +24,114 @@ typedef enum { NSString *path; } -// these are only appropriate for image type and return 0 otherwise +/** + Returns width if the blob object is an image, _0_ otherwise. + */ @property(nonatomic,readonly) NSInteger width; + +/** + Returns height if the blob object is an image, _0_ otherwise. + */ @property(nonatomic,readonly) NSInteger height; -// return a textual representation of the blob + +/** + Return a textual representation of the blob. + */ @property(nonatomic,readonly) NSString* text; -// Returns the data length +/** + Returns the data length. + */ @property(nonatomic,readonly) NSNumber* length; -// for file, data returns the size in bytes -// for image, returns the width x height +/** + Return the data size. + + For file, data returns the size in bytes, for image, returns the width x height. + */ @property(nonatomic,readonly) NSInteger size; +/** + Initialize the blob with an image. + @param image The image + */ -(id)initWithImage:(UIImage*)image; + +/** + Initialize the blob with data. + @param data_ The raw data. + @param mimetype_ The data mime type. + */ -(id)initWithData:(NSData*)data_ mimetype:(NSString*)mimetype_; + +/** + Initialize the blob with contents of a file. + @param path The path to the file. + */ -(id)initWithFile:(NSString*)path; +/** + Initialises blob with data. + @param data Th data to set. + */ -(void)setData:(NSData*)data; + +/** + Initializes blob with image. + @param image The image to set. + */ -(void)setImage:(UIImage*)image; + +/** + Sets the blob type. + @param mime The mime type string. + @param type The blob type. + */ -(void)setMimeType:(NSString*)mime type:(TiBlobType)type; +/** + Returns the blob type. + @return The blob type. + */ -(TiBlobType)type; + +/** + Returns the blob mime type. + @return The mime type string. + */ -(NSString*)mimeType; +/** + Returns the blob raw data. + @return The raw data. + */ -(NSData*)data; + +/** + Returns the blob image. + @return The image. + */ -(UIImage*)image; + +/** + Returns the blob file path. + @return The file path. + */ -(NSString*)path; --(NSString*)nativePath; // Android compatibility +/** + Returns the blob native path. + @return The blob native path (Android compatibility). + */ +-(NSString*)nativePath; + +/** + Tells the blob to write it's data to a file. + @param path The file path. + @param error The error result if failed. + @return _YES_ if the write operation succeeded, _NO_ otherwise. + */ -(BOOL)writeTo:(NSString*)path error:(NSError**)error; #pragma mark Image specific blob manipulations diff --git a/iphone/Classes/TiBuffer.h b/iphone/Classes/TiBuffer.h index 3217facb5a2..1133f7d6f8e 100644 --- a/iphone/Classes/TiBuffer.h +++ b/iphone/Classes/TiBuffer.h @@ -10,10 +10,16 @@ #import "TiBlob.h" // TODO: Support array-style access of bytes +/** + The class represents a buffer of bytes. + */ @interface TiBuffer : TiProxy { NSMutableData* data; NSNumber* byteOrder; } +/** + Provides access to raw data. + */ @property(nonatomic, retain) NSMutableData* data; // Public API @@ -29,8 +35,16 @@ -(TiBlob*)toBlob:(id)_void; -(NSString*)toString:(id)_void; +/** + Provides access to buffer length. + */ @property(nonatomic,assign) NSNumber* length; + +/** + Provides access to data byte order. + */ @property(nonatomic,retain) NSNumber* byteOrder; + // SPECIAL NOTES: // Ti.Buffer objects have an 'overloaded' Ti.Buffer[x] operation for x==int (making them behave like arrays). // See the code for how this works. diff --git a/iphone/Classes/TiColor.h b/iphone/Classes/TiColor.h index 970b96b03ee..cbc2bb0cfc6 100644 --- a/iphone/Classes/TiColor.h +++ b/iphone/Classes/TiColor.h @@ -7,19 +7,40 @@ #import #import "TiProxy.h" -// this is a UIColor proxy for cases where you need to return the color -// that was set and you need to return the original value (like #fff) back -// to the user - UIColor doesn't give you a way to get the RGB complements -// so this proxy does it for you - +/** + The UIColor proxy for cases where you need to return the color + that was set and you need to return the original value (like #fff) back + to the user - UIColor doesn't give you a way to get the RGB complements + so this proxy does it for you. + */ @interface TiColor : TiProxy { UIColor *color; NSString *name; } - +/** + Returns color proxy by name. + @param name The color name. + @return The color proxy object. + */ +(id)colorNamed:(NSString *)name; + +/** + Initializes the color proxy with color and name. + @param color The color. + @param name The color name. + */ -(id)initWithColor:(UIColor*)color name:(NSString*)name; + +/** + Returns the color. + @return The color. + */ -(UIColor*)_color; + +/** + Returns the color name. + @return The color name. + */ -(NSString*)_name; @end diff --git a/iphone/Classes/TiComplexValue.h b/iphone/Classes/TiComplexValue.h index fc5d0f6dd5c..f88ed44b3a8 100644 --- a/iphone/Classes/TiComplexValue.h +++ b/iphone/Classes/TiComplexValue.h @@ -5,20 +5,33 @@ * Please see the LICENSE included with this distribution for details. */ -// this is simply a wrapper for properties which have "withObject" -// argument semantics that need to be stored inside our proxy until the -// view is available. currently the key/value store of the properties -// makes it difficult to handle without marshalling them inside a wrapped -// container like this. - +/** + The simple wrapper for properties which have "withObject" + argument semantics that need to be stored inside our proxy until the + view is available. currently the key/value store of the properties + makes it difficult to handle without marshalling them inside a wrapped + container like this. + */ @interface TiComplexValue : NSObject { id value; NSDictionary *properties; } +/** + Initializes the value. + @param value The value to set. + @param properties The additional properties. + */ -(id)initWithValue:(id)value properties:(NSDictionary*)properties; +/** + Returns the underlying value. + */ @property(nonatomic,readonly) id value; + +/** + Returns the associated properties dictionary. + */ @property(nonatomic,readonly) NSDictionary *properties; @end diff --git a/iphone/Classes/TiDimension.h b/iphone/Classes/TiDimension.h index ef6c7dccbe4..d4d80103fab 100644 --- a/iphone/Classes/TiDimension.h +++ b/iphone/Classes/TiDimension.h @@ -16,6 +16,9 @@ typedef enum { TiDimensionTypePercent, } TiDimensionType; +/** + The dimension struct. + */ struct TiDimension { TiDimensionType type; CGFloat value; diff --git a/iphone/Classes/TiFile.h b/iphone/Classes/TiFile.h index e4847b3f5a7..e7cd642e87c 100644 --- a/iphone/Classes/TiFile.h +++ b/iphone/Classes/TiFile.h @@ -7,26 +7,58 @@ #import "TiProxy.h" -// main interface for File-based proxies -- this is in the API -// since Filesystem implements it but we want to be able to have other -// modules be able to cast to it transparently (such as database) -// but without causing a compile-time dependency on Filesystem module - +/** + The main interface for File-based proxies -- this is in the API + since Filesystem implements it but we want to be able to have other + modules be able to cast to it transparently (such as database) + but without causing a compile-time dependency on Filesystem module. + */ @interface TiFile : TiProxy { @protected NSString *path; BOOL deleteOnExit; } +/** + Returns absolute path of the file on file system. + */ @property(nonatomic,readonly) NSString *path; + +/** + Returns size of the file on file. + */ @property(nonatomic,readonly) unsigned long long size; +/** + Creates new instance of TiFile with specified path. + @param path The absolute path. + @return A created instance of TiFile. + */ -(id)initWithPath:(NSString*)path; + +/** + Creates new instance of TiFile for a temporary file with specified path. + + The references file will be deleted on file system when the TiFile object is released. + @param path The absolute path. + @return A created instance of TiFile. + */ -(id)initWithTempFilePath:(NSString*)path; +/** + Creates a new instance of TiFile for a temporary file created with specified extension in the default temporary folder. + @param extension The temporary file extension. + @return A created instance of TiFile. + */ +(TiFile*)createTempFile:(NSString*)extension; -(id)blob; + +/** + Returns the contents of the file as a TiBlob. + @param args Reserved for future use. + @return The TiBlob object. + */ -(id)toBlob:(id)args; @end diff --git a/iphone/Classes/TiLayoutQueue.h b/iphone/Classes/TiLayoutQueue.h index 49c9270929f..be20d9cac56 100644 --- a/iphone/Classes/TiLayoutQueue.h +++ b/iphone/Classes/TiLayoutQueue.h @@ -8,11 +8,23 @@ @class TiViewProxy; +/** + Layout queue utility class. + */ @interface TiLayoutQueue : NSObject { } +/** + Adds view proxy to the layout queue. + @param newViewProxy The view proxy to add. + */ +(void)addViewProxy:(TiViewProxy*)newViewProxy; + +/** + Forces view proxy refresh. + @param thisProxy The view proxy to layout. + */ +(void)layoutProxy:(TiViewProxy*)thisProxy; @end diff --git a/iphone/Classes/TiLocale.h b/iphone/Classes/TiLocale.h index 5daadefa4bf..2123044dace 100644 --- a/iphone/Classes/TiLocale.h +++ b/iphone/Classes/TiLocale.h @@ -7,16 +7,42 @@ #import "TiBase.h" +/** + The class represents locale. + */ @interface TiLocale : NSObject { NSString *currentLocale; NSBundle *bundle; } +/** + Returns the current locate. + @see currentLocale + */ @property(nonatomic,readwrite,retain) NSString *currentLocale; + +/** + Returns bundle. + */ @property(nonatomic,readwrite,retain) NSBundle *bundle; +/** + Return current locale. + @see currentLocale + */ +(NSString*)currentLocale; + +/** + Sets current locale. + @param locale The locale to set. + */ +(void)setLocale:(NSString*)locale; + +/** + Return localized text for the key. + @param key The text key. + @param comment The default value. + */ +(NSString*)getString:(NSString*)key comment:(NSString*)comment; @end diff --git a/iphone/Classes/TiModule.h b/iphone/Classes/TiModule.h index b63f2e4958a..064488324b3 100644 --- a/iphone/Classes/TiModule.h +++ b/iphone/Classes/TiModule.h @@ -9,6 +9,9 @@ @class TiHost; +/** + The base class for all Titanium modules + */ @interface TiModule : TiProxy { @protected @@ -26,18 +29,64 @@ -(id)createProxy:(NSArray*)args forName:(NSString*)name context:(id)evaluator; // module related utilities + +/** + Returns module identifier. + @return module identifier. + */ -(NSString*)moduleId; + +/** + Returns if the module is JS native module. + @return _YES_ if the module is JS native module, _NO_ ortherwise. + */ -(BOOL)isJSModule; + +/** + Returns the JS script data for the module. + @return The string containing JS code. + */ -(NSData*)moduleJS; + +/** + Converts a resource name in to a URL. + @param name The name of the resource. + @return The URL of the resource + */ -(NSURL*)moduleResourceURL:(NSString*)name; + -(id)bindCommonJSModule:(NSString*)code; -(id)bindCommonJSModuleForPath:(NSURL*)path; // lifecycle + +/** + Tells the module to startup. + */ -(void)startup; + +/** + Tells the module to shutdown. + @param sender The sender of the event. + */ -(void)shutdown:(id)sender; + +/** + Tells the module to suspend. + @param sender The sender of the event. + */ -(void)suspend:(id)sender; + +/** + Tells the module to resume. + @param sender The sender of the event. + */ -(void)resume:(id)sender; + +/** + Tells the module that it was resumed. + @param sender The sender of the event. + */ -(void)resumed:(id)sender; @end diff --git a/iphone/Classes/TiPoint.h b/iphone/Classes/TiPoint.h index 0fc889de107..98a0f400286 100644 --- a/iphone/Classes/TiPoint.h +++ b/iphone/Classes/TiPoint.h @@ -7,23 +7,47 @@ #import "TiProxy.h" #import "TiDimension.h" +/** + The class for point proxy. + */ @interface TiPoint : TiProxy { TiDimension xDimension; TiDimension yDimension; } +/** + Initializes the point object from point struct. + @param point_ The point struct. + */ -(id)initWithPoint:(CGPoint)point_; + -(id)initWithObject:(id)object; -(void)setValues:(id)object; -//Virtual property +/** + Provides access to point struct. + */ @property(nonatomic,assign) CGPoint point; +/** + Provides access to the point x coordinate. + */ @property(nonatomic,retain) NSNumber *x; + +/** + Provides access to the point y coordiante. + */ @property(nonatomic,retain) NSNumber *y; +/** + Returns the point x coordinate as a dimension. + */ @property(nonatomic,assign) TiDimension xDimension; + +/** + Returns the point y coordinate as a dimension. + */ @property(nonatomic,assign) TiDimension yDimension; diff --git a/iphone/Classes/TiProxy.h b/iphone/Classes/TiProxy.h index 65e6d832b13..c6a25a36d89 100644 --- a/iphone/Classes/TiProxy.h +++ b/iphone/Classes/TiProxy.h @@ -38,19 +38,47 @@ typedef enum { } TiProxyBridgeType; +/** + The proxy delegate protocol + */ @protocol TiProxyDelegate @required +/** + Tells the delegate that the proxy property has changed. + @param key The property name. + @param oldValue An old value of the property. + @param newValue A new value of the property. + @param proxy The proxy where the property has changed. + */ -(void)propertyChanged:(NSString*)key oldValue:(id)oldValue newValue:(id)newValue proxy:(TiProxy*)proxy; @optional +/** + Tells the delegate to read proxy values. + @param keys The enumeration of keys to read. + */ -(void)readProxyValuesWithKeys:(id)keys; +/** + Tells the delegate that a listener has been added to the proxy. + @param type The listener type. + @param count The current number of active listeners + */ -(void)listenerAdded:(NSString*)type count:(int)count; + +/** + Tells the delegate that a listener has been removed to the proxy. + @param type The listener type. + @param count The current number of active listeners after the remove + */ -(void)listenerRemoved:(NSString*)type count:(int)count; +/** + Tells the delegate to detach from proxy. + */ -(void)detachProxy; @end @@ -63,6 +91,9 @@ void DoProxyDelegateReadValuesWithKeysFromProxy(UIView * target //Why are these here? Because they can be commonly used between TiUIView and TiUITableViewCell. +/** + The base class for Titanium proxies. + */ @interface TiProxy : NSObject { @private NSMutableDictionary *listeners; @@ -89,6 +120,9 @@ void DoProxyDelegateReadValuesWithKeysFromProxy(UIView * target @property(readonly,nonatomic) id pageContext; @property(readonly,nonatomic) id executionContext; +/** + Provides access to proxy delegate. + */ @property(nonatomic,retain,readwrite) id modelDelegate; +(BOOL)shouldRegisterOnInit; @@ -112,8 +146,23 @@ void DoProxyDelegateReadValuesWithKeysFromProxy(UIView * target -(TiProxy*)currentWindow; -(void)contextShutdown:(id)sender; -(id)toString:(id)args; + +/** + Returns if the proxy was destroyed. + @return _YES_ if destroyed, _NO_ otherwise. + */ -(BOOL)destroyed; + +/** + Tells the proxy that it is in reproxying stage. + @param yn _YES_ if the proxy is in reproxying stage, _NO_ otherwise. + */ -(void)setReproxying:(BOOL)yn; + +/** + Returns if the proxy is in reproxying stage. + @return _YES_ if the proxy is in reproxying stage, _NO_ otherwise. + */ -(BOOL)inReproxy; #pragma mark Utility @@ -122,17 +171,45 @@ void DoProxyDelegateReadValuesWithKeysFromProxy(UIView * target -(BOOL)retainsJsObjectForKey:(NSString *)key; //TODO: Find everywhere were we retain a proxy in a non-assignment way, and do remember/forget properly. + +/** + Tells the proxy to associate another proxy with it. + + The associated proxy will be retained. + @param rememberedProxy The proxy to remember. + */ -(void)rememberProxy:(TiProxy *)rememberedProxy; + +/** + Tells the proxy to deassociate another proxy with it. + + The deassociated proxy will be released. + @param forgottenProxy The proxy to forget. + */ -(void)forgetProxy:(TiProxy *)forgottenProxy; + //These are when, say, a window is opened, so you want to do tiValueProtect to make SURE it doesn't go away. + +/** + Tells the proxy to retain associated JS object. + */ -(void)rememberSelf; + +/** + Tells the proxy to release associated JS object. + */ -(void)forgetSelf; //SetCallback is done internally by setValue:forUndefinedKey: -(void)fireCallback:(NSString*)type withArg:(NSDictionary *)argDict withSource:(id)source; #pragma mark Public + +/** + Returns keys of all properties associated with the proxy. + */ -(id)allKeys; + -(NSArray *)keySequence; +(void)throwException:(NSString *) reason subreason:(NSString*)subreason location:(NSString *)location; diff --git a/iphone/Classes/TiRange.h b/iphone/Classes/TiRange.h index 5b99845749f..cb659e94436 100644 --- a/iphone/Classes/TiRange.h +++ b/iphone/Classes/TiRange.h @@ -5,14 +5,28 @@ * Please see the LICENSE included with this distribution for details. */ +/** + The class representing a range object. + */ @interface TiRange : NSObject { NSRange range; } +/** + Initializes the range object from range struct. + @param range The range struct. + */ -(id)initWithRange:(NSRange)range; +/** + Provides access to the range location. + */ @property(nonatomic,readwrite,assign) id location; + +/** + Provides access to the range length. + */ @property(nonatomic,readwrite,assign) id length; @end diff --git a/iphone/Classes/TiRect.h b/iphone/Classes/TiRect.h index b06ca125053..011b3d71904 100644 --- a/iphone/Classes/TiRect.h +++ b/iphone/Classes/TiRect.h @@ -6,16 +6,43 @@ */ #import "TiProxy.h" +/** + The class for rectangle object proxy. + */ @interface TiRect : TiProxy { CGRect rect; } +/** + Initializes the rect proxy from rect struct. + @param rect_ The rect struct. + */ -(void)setRect:(CGRect)rect_; + +/** + Returns rect struct. + @return The rect struct. + */ -(CGRect)rect; +/** + Provides access to rectangle x coordinate. + */ @property(nonatomic,retain) NSNumber *x; + +/** + Provides access to rectangle y coordinate. + */ @property(nonatomic,retain) NSNumber *y; + +/** + Provides access to rectangle width. + */ @property(nonatomic,retain) NSNumber *width; + +/** + Provides access to rectangle height. + */ @property(nonatomic,retain) NSNumber *height; @end diff --git a/iphone/Classes/TiRootController.h b/iphone/Classes/TiRootController.h index cd9459ac50f..2f6389678fe 100644 --- a/iphone/Classes/TiRootController.h +++ b/iphone/Classes/TiRootController.h @@ -8,25 +8,94 @@ #import #import "TiWindowProxy.h" +/** + Protocol for root controller. + */ @protocol TiRootController @required + +/** + Tells the root controller that a window became focused. + @param focusedViewController The focused view controller. + */ -(void)windowFocused:(UIViewController*)focusedViewController; + +/** + Tells the root controller that a window was closed. + @param closedViewController The closed view controller. + */ -(void)windowClosed:(UIViewController *)closedViewController; +/** + Tells the root controller to resize it's view to the size of main screen. + @return The bounds of the view after resize. + */ -(CGRect)resizeView; + +/** + Tells the root controller to reposition all it's subviews. + */ -(void)repositionSubviews; +/** + Tells the root controller to set background color on it's view. + @param color The color to set. + @see setBackgroundImage: + */ -(void)setBackgroundColor:(UIColor*)color; + +/** + Tells the root controller to set background image on it's view. + @param backgroundImage The background image to set. + @see setBackgroundColor: + */ -(void)setBackgroundImage:(UIImage*) backgroundImage; +/** + Tells the root controller that the view controller will hide. + @param focusedViewController The view controller to hide. + @param animated The animation flag. + */ - (void)willHideViewController:(UIViewController *)focusedViewController animated:(BOOL)animated; + +/** + Tells the root controller that the view controller was hidden. + @param focusedViewController The view controller hidden. + @param animated The animation flag. + */ - (void)didHideViewController:(UIViewController *)focusedViewController animated:(BOOL)animated; + +/** + Tells the root controller that the view controller will show. + @param focusedViewController The view controller to show. + @param animated The animation flag. + */ - (void)willShowViewController:(UIViewController *)focusedViewController animated:(BOOL)animated; + +/** + Tells the root controller that the view controller was shown. + @param focusedViewController The view controller shown. + @param animated The animation flag. + */ - (void)didShowViewController:(UIViewController *)focusedViewController animated:(BOOL)animated; +/** + Tells the root controller that the keyboard received a focus. + @param visibleProxy The view proxy that received keyboard focus. + */ -(void)didKeyboardFocusOnProxy:(TiViewProxy *)visibleProxy; + +/** + Tells the root controller that the keyboard was blurred. + @param blurredProxy The view proxy that blurred keyboard focus. + */ -(void)didKeyboardBlurOnProxy:(TiViewProxy *)blurredProxy; +/** + Returns if the window proxy is the top window. + @param window The window proxy + @return _YES_ if the window proxy is the top window, _NO_ otherwise. + */ -(BOOL)isTopWindow:(TiWindowProxy*)window; @end diff --git a/iphone/Classes/TiRootViewController.h b/iphone/Classes/TiRootViewController.h index 8f6e5daec2a..1f65178d6e6 100644 --- a/iphone/Classes/TiRootViewController.h +++ b/iphone/Classes/TiRootViewController.h @@ -8,6 +8,9 @@ #import "TiRootController.h" #import "TiWindowProxy.h" +/** + The class represent root controller in a view hierarchy. + */ @interface TiRootViewController : UIViewController { @private //Presentation: background image and color. @@ -54,21 +57,64 @@ CGFloat leaveDuration; } +/** + Returns visibility of on-screen keyboard. + */ @property(nonatomic,readonly) BOOL keyboardVisible; + +/** + Returns image view being displayed while application's view is loading. + */ @property(nonatomic,readonly) UIImageView * defaultImageView; + +/** + Returns current window orientation. + */ @property(nonatomic,readonly) UIInterfaceOrientation windowOrientation; + +/** + Tells the controller to hides and release the default image view. + @see defaultImageView + */ -(void)dismissDefaultImageView; +/** + Provides access to background color of the view represented by the root view controller. + @see backgroundImage + */ @property(nonatomic,readwrite,retain) UIColor * backgroundColor; + +/** + Provides access to background image of the view represented by the root view controller. + @see backgroundColor + */ @property(nonatomic,readwrite,retain) UIImage * backgroundImage; +/** + Returns currently focused view controller. + @return Focused view controller. + */ -(UIViewController *)focusedViewController; -(void)windowFocused:(UIViewController*)focusedViewController; -(void)windowClosed:(UIViewController *)closedViewController; +/** + Tells the controller to resize it's view to the size of main screen. + @return The bounds of the view after resize. + */ -(CGRect)resizeView; + +/** + Tells the controller to resize it's view to the size of main screen adjusted according to visibility of status bar. + @param statusBarHidden If _YES_, sets view size as if status bar is hidden; otherwise, does not. + @return The bounds of the view after resize. + */ -(CGRect)resizeViewForStatusBarHidden:(BOOL)statusBarHidden; + +/** + Tells the controller to reposition all it's subviews. + */ -(void)repositionSubviews; -(void)refreshOrientationWithDuration:(NSTimeInterval) duration; @@ -76,7 +122,18 @@ -(void)manuallyRotateToOrientation:(UIInterfaceOrientation)newOrientation duration:(NSTimeInterval)duration; -(UIInterfaceOrientation)lastValidOrientation; +/** + Tells the controller to open the specified window proxy. + @param window The window proxy to open. + @param args Reserved for future use. + */ - (void)openWindow:(TiWindowProxy *)window withObject:(id)args; + +/** + Tells the controller to close the specified window proxy. + @param window The window proxy to close. + @param args Reserved for future use. + */ - (void)closeWindow:(TiWindowProxy *)window withObject:(id)args; @end diff --git a/iphone/Classes/TiTab.h b/iphone/Classes/TiTab.h index 1223a88a8ef..bab8583b254 100644 --- a/iphone/Classes/TiTab.h +++ b/iphone/Classes/TiTab.h @@ -9,17 +9,34 @@ @class TiProxy; @class TiWindowProxy; +/** + The protocol for tabs. + */ @protocol TiTab @required +/** + Returns the tag group associated with the tab. + @return A tab group. + */ -(TiProxy*)tabGroup; +/** + Returns the navigation controller associated with the tab. + @return A navigation controller. + */ -(UINavigationController*)controller; -(void)open:(NSArray*)args; -(void)close:(NSArray*)args; + +/** + Tells the tab that it's associated window is closing. + @param window The window being closed. + @param animated _YES_ if window close is anumated, _NO_ otherwise. + */ -(void)windowClosing:(TiWindowProxy*)window animated:(BOOL)animated; @end diff --git a/iphone/Classes/TiTabController.h b/iphone/Classes/TiTabController.h index e13c5f4579c..1d69b1cb250 100644 --- a/iphone/Classes/TiTabController.h +++ b/iphone/Classes/TiTabController.h @@ -5,8 +5,14 @@ * Please see the LICENSE included with this distribution for details. */ +/** + The protocol for tab controller. + */ @protocol TiTabController +/** + Returns the window associated with the tab controller. + */ -(id)window; @end diff --git a/iphone/Classes/TiTabGroup.h b/iphone/Classes/TiTabGroup.h index 74e68b4ffaf..f90bd277f66 100644 --- a/iphone/Classes/TiTabGroup.h +++ b/iphone/Classes/TiTabGroup.h @@ -8,8 +8,15 @@ #import +/** + The tab group protocol + */ @protocol TiTabGroup +/** + Returns the tab bar for the tag group. + @return The tag bar. + */ -(UITabBar*)tabbar; @end diff --git a/iphone/Classes/TiToolbar.h b/iphone/Classes/TiToolbar.h index df9a7bcba5e..29391eb19c0 100644 --- a/iphone/Classes/TiToolbar.h +++ b/iphone/Classes/TiToolbar.h @@ -8,12 +8,19 @@ // marker interface for toolbars +/** + Toolbar proxy class. + */ @interface TiToolbar : TiViewProxy { @private } +/** + Returns the underlying toolbar. + @return The toolbar. + */ -(UIToolbar*)toolbar; @end diff --git a/iphone/Classes/TiToolbarButton.h b/iphone/Classes/TiToolbarButton.h index 1704ea39fc9..9ab1b8db58c 100644 --- a/iphone/Classes/TiToolbarButton.h +++ b/iphone/Classes/TiToolbarButton.h @@ -7,10 +7,27 @@ #include "TiToolbar.h" +/** + The protocol for toolbar button. + */ @protocol TiToolbarButton +/** + Attaches the toolbar button to the specified toolbar. + @param toolbar The toolbar to attach to. + */ -(void)setToolbar:(TiToolbar*)toolbar; + +/** + Returns the toolbar the button is attached to. + @return The toolbar. + */ -(TiToolbar*)toolbar; + +/** + Returns if the button it attached to a toolbar. + @return _YES_ if the button is attached to a toolbar, _NO_ otherwise. + */ -(BOOL)attachedToToolbar; @end diff --git a/iphone/Classes/TiUIView.h b/iphone/Classes/TiUIView.h index 01e96584125..48ba0579db6 100644 --- a/iphone/Classes/TiUIView.h +++ b/iphone/Classes/TiUIView.h @@ -11,11 +11,30 @@ //By declaring a scrollView protocol, TiUITextWidget can access @class TiUIView; + +/** + The protocol for scroll view. + */ @protocol TiUIScrollView +/** + Tells the scroll view that keyboard did show. + @param keyboardTop The keyboard height. + */ -(void)keyboardDidShowAtHeight:(CGFloat)keyboardTop; + +/** + Tells the scroll view to scroll to make the specified view visible. + @param firstResponderView The view to make visible. + @param keyboardTop The keyboard height. + */ -(void)scrollToShowView:(TiUIView *)firstResponderView withKeyboardHeight:(CGFloat)keyboardTop; +/** + Tells the scroll view that keyboard did show. + @param keyboardTop The keyboard height. + @param firstResponderView The view for which keyboard was shown. + */ -(void)keyboardDidShowAtHeight:(CGFloat)keyboardTop forView:(TiUIView *)firstResponderView; @end @@ -27,6 +46,10 @@ void ModifyScrollViewForKeyboardHeightAndContentHeightWithResponderRect(UIScroll @class TiViewProxy; +/** + Base class for all Titanium views. + @see TiViewProxy + */ @interface TiUIView : UIView { @private @@ -65,12 +88,39 @@ void ModifyScrollViewForKeyboardHeightAndContentHeightWithResponderRect(UIScroll TiDimension leftCap; TiDimension topCap; } + +/** + Returns current status of the view animation. + @return _YES_ if view is being animated, _NO_ otherwise. + */ -(BOOL)animating; +/** + Provides access to a proxy object of the view. + */ @property(nonatomic,readwrite,assign) TiProxy *proxy; + +/** + Provides access to touch delegate of the view. + + Touch delegate is the control that receives all touch events. + */ @property(nonatomic,readwrite,assign) UIView *touchDelegate; + +/** + Returns view's transformation matrix. + */ @property(nonatomic,readonly) id transformMatrix; + +/** + Provides access to background image of the view. + */ @property(nonatomic,readwrite,retain) id backgroundImage; + +/** + Returns enablement of touch events. + @see updateTouchHandling + */ @property(nonatomic,readonly) BOOL touchEnabled; @property(nonatomic,readonly) UITapGestureRecognizer* singleTapRecognizer; @@ -81,33 +131,96 @@ void ModifyScrollViewForKeyboardHeightAndContentHeightWithResponderRect(UIScroll @property(nonatomic,readonly) UISwipeGestureRecognizer* rightSwipeRecognizer; @property(nonatomic,readonly) UILongPressGestureRecognizer* longPressRecognizer; +/** + Returns CA layer for the background of the view. + */ -(CALayer *)backgroundImageLayer; +/** + Tells the view to start specified animation. + @param newAnimation The animation to start. + */ -(void)animate:(TiAnimation *)newAnimation; #pragma mark Framework +/** + Performs view's initialization procedure. + */ -(void)initializeState; + +/** + Performs view's configuration procedure. + */ -(void)configurationSet; + +/** + Sets virtual parent transformation for the view. + @param newTransform The transformation to set. + */ -(void)setVirtualParentTransform:(CGAffineTransform)newTransform; -(void)setTransform_:(id)matrix; +/** + Tells the view to load an image. + @param image The string referring the image. + @return The loaded image. + */ -(UIImage*)loadImage:(id)image; -(id)proxyValueForKey:(NSString *)key; -(void)readProxyValuesWithKeys:(id)keys; + +/** + Tells the view to change it's proxy to the new one provided. + @param newProxy The new proxy to set on the view. + */ -(void)transferProxy:(TiViewProxy*)newProxy; +/** + Tells the view to update it's touch handling state. + @see touchEnabled + */ -(void)updateTouchHandling; + +/** + Tells the view that it's frame and/or bounds has chnaged. + @param frame The frame rect + @param bounds The bounds rect + */ -(void)frameSizeChanged:(CGRect)frame bounds:(CGRect)bounds; + +/** + Tells the view to make it's root view a first responder. + */ -(void)makeRootViewFirstResponder; + -(void)animationCompleted; +/** + The convenience method to raise an exception for the view. + @param reason The exception reason. + @param subreason The exception subreason. + @param location The exception location. + */ +(void)throwException:(NSString *) reason subreason:(NSString*)subreason location:(NSString *)location; + -(void)throwException:(NSString *) reason subreason:(NSString*)subreason location:(NSString *)location; +/** + Returns default enablement for interactions. + + Subclasses may override. + @return _YES_ if the control has interactions enabled by default, _NO_ otherwise. + */ -(BOOL)interactionDefault; + -(BOOL)interactionEnabled; + +/** + Returns if the view has any touchable listeners attached. + @return _YES_ if the control has any touchable listener attached, _NO_ otherwise. + */ -(BOOL)hasTouchableListener; -(void)handleControlEvents:(UIControlEvents)events; diff --git a/iphone/Classes/TiUtils.h b/iphone/Classes/TiUtils.h index ad5731dd9f5..664e0c33c5d 100644 --- a/iphone/Classes/TiUtils.h +++ b/iphone/Classes/TiUtils.h @@ -20,17 +20,44 @@ typedef enum { TOO_SMALL = -32, } EncodingError; +/** + Utilities class. + */ @interface TiUtils : NSObject { } -+(NSString *)UTCDateForDate:(NSDate*)data; +/** + Converts date to UTC format. + @param date The date + @return The date string in UTC format. + */ ++(NSString *)UTCDateForDate:(NSDate*)date; + +/** + Converts string in UTC format into a date. + @param The date string in UTC format. + @return The converted date. + */ +(NSDate *)dateForUTCDate:(NSString*)date; +/** + Returns current date in UTC format. + @return The date string in UTC format. + */ +(NSString *)UTCDate; +/** + Generates a new UUID. + @return The generate UUID. + */ +(NSString*)createUUID; +/** + Creates a temporary file with name extension. + @param extension The filename extension. + @return The created temporary file object. + */ +(TiFile*)createTempFile:(NSString*)extension; +(NSData *)loadAppResource:(NSURL*)url; diff --git a/iphone/Classes/TiViewController.h b/iphone/Classes/TiViewController.h index f496b079083..bc84bc018c9 100644 --- a/iphone/Classes/TiViewController.h +++ b/iphone/Classes/TiViewController.h @@ -7,30 +7,82 @@ #import "TiViewProxy.h" +/** + The protocol for view controllers. + */ @protocol TiUIViewController @required - (UIViewController *)childViewController; -- (void)viewWillAppear:(BOOL)animated; // Called when the view is about to made visible. Default does nothing -- (void)viewDidAppear:(BOOL)animated; // Called when the view has been fully transitioned onto the screen. Default does nothing -- (void)viewWillDisappear:(BOOL)animated; // Called when the view is dismissed, covered or otherwise hidden. Default does nothing -- (void)viewDidDisappear:(BOOL)animated; // Called after the view was dismissed, covered or otherwise hidden. Default does nothing +/** + Tells the view controller that it's view will appear. + + Called when the view is about to made visible. Default does nothing. + @param animated The animation flag. + */ +- (void)viewWillAppear:(BOOL)animated; + +/** + Tells the view controller that it's view did appear. + + Called when the view has been fully transitioned onto the screen. Default does nothing. + @param animated The animation flag. + */ +- (void)viewDidAppear:(BOOL)animated; + +/** + Tells the view controller that it's view will disappear. + + Called when the view is dismissed, covered or otherwise hidden. Default does nothing. + @param animated The animation flag. + */ +- (void)viewWillDisappear:(BOOL)animated; + +/** + Tells the view controller that it's view did disappear. + + Called after the view was dismissed, covered or otherwise hidden. Default does nothing. + @param animated The animation flag. + */ +- (void)viewDidDisappear:(BOOL)animated; @optional +/** + Tells the view controller that it's view will be rotated to interface orientation. + @param toInterfaceOrientation The target interface orientation. + @param duration The duration of the rotation animation. + */ - (void)willAnimateRotationToInterfaceOrientation:(UIInterfaceOrientation)toInterfaceOrientation duration:(NSTimeInterval)duration; +/** + Tells the view controller to ignore rotation to specified orientation. + @param orientation The orientation to ignore. + */ -(void)ignoringRotationToOrientation:(UIInterfaceOrientation)orientation; @end +/** + The base class for Titanium view controllers. + */ @interface TiViewController : UIViewController { TiViewProxy *proxy; } +/** + Initialize the view controller with the provided view proxy. + @param window The view proxy associated with the view controller. + @return A new view controller. + */ -(id)initWithViewProxy:(TiViewProxy*)window; + +/** + Provides access to view proxy associated with the view controller. + */ @property(nonatomic,readwrite,assign) TiViewProxy *proxy; + @end diff --git a/iphone/Classes/TiViewProxy.h b/iphone/Classes/TiViewProxy.h index 811e96cd3e4..81c94298d2e 100644 --- a/iphone/Classes/TiViewProxy.h +++ b/iphone/Classes/TiViewProxy.h @@ -8,14 +8,35 @@ #import "TiUIView.h" #import +/** + Protocol for the view that could receive keyboard focus. + */ @protocol TiKeyboardFocusableView #pragma mark Public Titanium APIs. + +/** + Tells the view to focus. + @param args Unused. + */ - (void)focus:(id)args; + +/** + Tells the view to blur. + @param args Unused. + */ - (void)blur:(id)args; #pragma mark Private internal APIs. + +/** + Returns keyboard accessory view. + */ @property(nonatomic,readonly) UIView * keyboardAccessoryView; + +/** + Returns keyboard accessory height. + */ @property(nonatomic,readonly) CGFloat keyboardAccessoryHeight; @end @@ -36,6 +57,11 @@ enum @class TiAction, TiBlob; //For TableRows, we need to have minimumParentHeightForWidth: + +/** + The class represents a proxy that is attached to a view. + The class is not intended to be overriden. + */ @interface TiViewProxy : TiProxy { @protected @@ -88,14 +114,50 @@ enum } #pragma mark public API + +/** + Provides access to z-index value. + */ @property(nonatomic,readwrite,assign) int zIndex; + +/** + Provides access to visibility of parent view proxy. + */ @property(nonatomic,readwrite,assign) BOOL parentVisible; // For tableview magic ONLY + +/** + Returns children view proxies for the proxy. + */ @property(nonatomic,readonly) NSArray *children; +/** + Tells the view proxy to add a child proxy. + @param arg A single proxy to add or NSArray of proxies. + */ -(void)add:(id)arg; + +/** + Tells the view proxy to remove a child proxy. + @param arg A single proxy to remove. + */ -(void)remove:(id)arg; + +/** + Tells the view proxy to set visibility on a child proxy to _YES_. + @param arg A single proxy to show. + */ -(void)show:(id)arg; + +/** + Tells the view proxy to set visibility on a child proxy to _NO_. + @param arg A single proxy to hide. + */ -(void)hide:(id)arg; + +/** + Tells the view proxy to run animation on it's view. + @param arg An animation object. + */ -(void)animate:(id)arg; -(void)setTop:(id)value; @@ -111,6 +173,7 @@ enum -(void)setSize:(id)value; -(void)setCenter:(id)value; + -(TiPoint*)center; -(id)animatedCenter; @@ -119,10 +182,24 @@ enum #pragma mark nonpublic accessors not related to Housecleaning + +/** + Provides access to parent proxy of the view proxy. + @see add: + @see remove: + @see children + */ @property(nonatomic, assign) TiViewProxy *parent; //TODO: make this a proper readwrite property declaration. +/** + Provides access to layout properties of the underlying view. + */ @property(nonatomic,readonly,assign) LayoutConstraint * layoutProperties; + +/** + Provides access to sandbox bounds of the underlying view. + */ @property(nonatomic,readwrite,assign) CGRect sandboxBounds; //This is unaffected by parentVisible. So if something is truely visible, it'd be [self visible] && parentVisible. -(void)setHidden:(BOOL)newHidden withArgs:(id)args; @@ -133,78 +210,277 @@ enum //NOTE: DO NOT SET VIEW UNLESS IN A TABLE VIEW, AND EVEN THEN. @property(nonatomic,readwrite,retain)TiUIView * view; +/** + Returns language convertion table. + + Subclasses may override. + @return The dictionary + */ -(NSMutableDictionary*)langConversionTable; #pragma mark Methods subclasses should override for behavior changes + +/** + Returns if the view proxy needs to suppress relayout. + + Subclasses may override. + @return _YES_ if relayout should be suppressed, _NO_ otherwise. + */ -(BOOL)suppressesRelayout; + +/** + Returns if the view proxy supports navigation bar positioning. + + Subclasses may override. + @return _YES_ if navigation bar positioning is supported, _NO_ otherwise. + */ -(BOOL)supportsNavBarPositioning; + +/** + Returns if the view proxy can have a UIController object in its parent view. + + Subclasses may override. + @return _YES_ if the view proxy can have a UIController object in its parent view + */ -(BOOL)canHaveControllerParent; + +/** + Returns if the view proxy should detach it's view on unload. + + Subclasses may override. + @return _YES_ if the view should be detached, _NO_ otherwise. + */ -(BOOL)shouldDetachViewOnUnload; + +/** + Returns parent view for child proxy. + + The method is used in cases when proxies heirarchy is different from views hierarchy. + Subclasses may override. + @param child The child view proxy for which return the parent view. + @return The parent view + */ -(UIView *)parentViewForChild:(TiViewProxy *)child; #pragma mark Event trigger methods + +/** + Tells the view proxy that the attached window will open. + @see windowDidOpen + */ -(void)windowWillOpen; + +/** + Tells the view proxy that the attached window did open. + @see windowWillOpen + */ -(void)windowDidOpen; + +/** + Tells the view proxy that the attached window will close. + @see windowDidClose + */ -(void)windowWillClose; + +/** + Tells the view proxy that the attached window did close. + @see windowWillClose + */ -(void)windowDidClose; +/** + Tells the view proxy that it's properties are about to change. + @see didFirePropertyChanges + */ -(void)willFirePropertyChanges; + +/** + Tells the view proxy that it's properties are changed. + @see willFirePropertyChanges + */ -(void)didFirePropertyChanges; +/** + Tells the view proxy that a view will be attached to it. + @see viewDidAttach + */ -(void)viewWillAttach; // Need this for video player & possibly other classes which override newView + +/** + Tells the view proxy that a view was attached to it. + @see viewWillAttach + */ -(void)viewDidAttach; + +/** + Tells the view proxy that a view will be detached from it. + @see viewDidDetach + */ -(void)viewWillDetach; + +/** + Tells the view proxy that a view was detached from it. + @see viewWillDetach + */ -(void)viewDidDetach; #pragma mark Housecleaning state accessors //TODO: Sounds like the redundancy department of redundancy was here. + +/** + Returns if a view is attached to the view proxy. + @return _YES_ if the view proxy has a view attached to it, _NO_ otherwise. + */ -(BOOL)viewAttached; + +/** + Returns if the view proxy has been initialized. + @return _YES_ if the view proxy has been initialized, _NO_ otherwise. + */ -(BOOL)viewInitialized; + +/** + Returns if the view proxy has been completely set up. + @return _YES_ if the view proxy has been initialized and it's view has a superview and non-empty bounds, _NO_ otherwise. + */ -(BOOL)viewReady; + +/** + Returns if a window attached to the view proxy has been opened. + @return _YES_ if the view proxy's window has been opened, _NO_ otherwise. + */ -(BOOL)windowHasOpened; + +/** + Returns if a window attached to the view proxy is currently being opened. + @return _YES_ if the view proxy's window is being opened, _NO_ otherwise. + */ -(BOOL)windowIsOpening; +/** + Returns if the view proxy is using a bar button item. + @return _YES_ if a bar button item is used, _NO_ otherwise. + */ -(BOOL)isUsingBarButtonItem; -(CGRect)appFrame; //TODO: Why is this here? It doesn't have anything to do with a specific instance. #pragma mark Building up and tearing down -(void)firePropertyChanges; + +/** + Returns a ne view corresponding to the view proxy. + @return The created view. + */ -(TiUIView*)newView; +/** + Tells the view proxy to detach it's view. + */ -(void)detachView; + -(void)destroy; + + +/** + Tells the view proxy to remove it's bar button item. + */ -(void)removeBarButtonView; #pragma mark Callbacks +/** + Tells the view proxy that it's view animation did complete. + @param animation The completed animation + */ -(void)animationCompleted:(TiAnimation*)animation; + +/** + Tells the view attached to the view proxy to perform the specified action. + @param action The action to perform. + */ -(void)makeViewPerformAction:(TiAction *)action; +/** + Tells the view attached to the view proxy to perform a selector with given arguments. + @param selector The selector to perform. + @param object The argument for the method performed. + @param create The flag to create the view if the one is not attached. + @param wait The flag to wait till the operation completes. + */ -(void)makeViewPerformSelector:(SEL)selector withObject:(id)object createIfNeeded:(BOOL)create waitUntilDone:(BOOL)wait; #pragma mark Layout events, internal and external +/** + Tells the view proxy that the attached view size will change. + */ -(void)willChangeSize; + +/** + Tells the view proxy that the attached view position will change. + */ -(void)willChangePosition; + +/** + Tells the view proxy that the attached view z-index will change. + */ -(void)willChangeZIndex; + +/** + Tells the view proxy that the attached view layout will change. + */ -(void)willChangeLayout; + +/** + Tells the view proxy that the attached view will show. + */ -(void)willShow; + +/** + Tells the view proxy that the attached view will hide. + */ -(void)willHide; +/** + Tells the view proxy that the attached view contents will change. + */ -(void)contentsWillChange; +/** + Tells the view proxy that the attached view's parent size will change. + */ -(void)parentSizeWillChange; + +/** + Tells the view proxy that the attached view's parent will relay. + */ -(void)parentWillRelay; + +/** + Tells the view proxy that the attached view's parent will show. + */ -(void)parentWillShow; + +/** + Tells the view proxy that the attached view's parent will hide. + */ -(void)parentWillHide; #pragma mark Layout actions -(void)refreshView:(TiUIView *)transferView; +/** + Tells the view proxy to force size refresh of the attached view. + */ -(void)refreshSize; + +/** + Tells the view proxy to force position refresh of the attached view. + */ -(void)refreshPosition; + -(void)willEnqueue; //Unlike the other layout actions, this one is done by the parent of the one called by refreshView. diff --git a/iphone/Classes/TiWindowProxy.h b/iphone/Classes/TiWindowProxy.h index 8e50e6ff87b..94f4dcae410 100644 --- a/iphone/Classes/TiWindowProxy.h +++ b/iphone/Classes/TiWindowProxy.h @@ -29,19 +29,36 @@ typedef enum #define TI_ORIENTATION_ALLOWED(flag,bit) (flag & (1< +/** + Provides access to parent orientation controller. + */ @property(nonatomic,readwrite,assign) id parentOrientationController; + +/** + Returns orientation flags. + */ @property(nonatomic,readonly,assign) TiOrientationFlags orientationFlags; + +/** + Tells the controller that child orientation controller has changed flags. + @param orientationController The child orientation controller + */ -(void)childOrientationControllerChangedFlags:(id) orientationController; @end TiOrientationFlags TiOrientationFlagsFromObject(id args); -// specialization for TiViews that act like top level -// windows when opened, closed, etc. -// + +/** + The class is a specialization for TiViews that act like top level + windows when opened, closed, etc. + */ @interface TiWindowProxy : TiViewProxy { @protected BOOL opened; @@ -71,22 +88,50 @@ TiOrientationFlags TiOrientationFlagsFromObject(id args); TiOrientationFlags orientationFlags; } +/** + Provides access to parent oriantation controller. + */ @property(nonatomic,readwrite,assign) id parentOrientationController; + +/** + Provides access to window orientation flags. + */ @property(nonatomic,readonly,assign) TiOrientationFlags orientationFlags; +/** + Tells the window proxy to fire focus event. + @param newFocused _YES_ to fire _focus_ event, _blur_ otherwise. + */ -(void)fireFocus:(BOOL)newFocused; +/** + Returns if the window is being opened. + */ @property(nonatomic,readonly) BOOL opening; #pragma mark Public APIs @property(nonatomic,readonly) NSNumber *opened; @property(nonatomic,readonly) NSNumber *focused; + +/** + Returns if the window is being closed. + */ @property(nonatomic,readonly) BOOL closing; -(void)open:(id)args; -(void)close:(id)args; + +/** + Returns the tag group the proxy's window is attached to if any. + @return The tag group proxy the window is attached to. + */ -(TiProxy*)tabGroup; + +/** + The tab in tag group the proxy's window is associated with if any. + @return The tab proxy the window is accosiated with + */ -(TiProxy*)tab; #pragma mark Internal @@ -97,7 +142,14 @@ TiOrientationFlags TiOrientationFlagsFromObject(id args); -(void)_associateTab:(UIViewController*)controller_ navBar:(UINavigationController*)navbar_ tab:(TiProxy*)tab_; -(void)prepareForNavView:(UINavigationController*)navController_; +/** + Returns view controller for the window's view. + */ @property(nonatomic,readwrite,retain) UIViewController *controller; + +/** + Returns navigation controller for the window's view. + */ @property(nonatomic,readwrite,retain) UINavigationController *navController; -(void)releaseController; @@ -113,6 +165,9 @@ TiOrientationFlags TiOrientationFlagsFromObject(id args); -(void)_tabBeforeFocus; -(void)_tabBeforeBlur; +/** + Tells the window proxy to setup window's decorations. + */ -(void)setupWindowDecorations; @end diff --git a/iphone/Classes/WebFont.h b/iphone/Classes/WebFont.h index 06ea137092b..86d3a0ae807 100644 --- a/iphone/Classes/WebFont.h +++ b/iphone/Classes/WebFont.h @@ -8,6 +8,9 @@ #import +/** + The class representin a web font. + */ @interface WebFont : NSObject { NSString* family; CGFloat size; @@ -18,22 +21,85 @@ BOOL isNormalStyle; UIFont *font; } + +/** + Provides access to web font family. + */ @property(nonatomic,retain) NSString *family; + +/** + Provides access to web font size. + */ @property(nonatomic) CGFloat size; + +/** + Returns if the web font size if set. + @return _YES_ if font size is set, _NO_ otherwise. + */ @property(nonatomic,readonly) BOOL isSizeNotSet; + +/** + Returns if the web font weight is bold. + */ @property(nonatomic) BOOL isBoldWeight; + +/** + Returns if the web font weight is normal. + */ @property(nonatomic) BOOL isNormalWeight; + +/** + Returns if the web font style is italic. + */ @property(nonatomic) BOOL isItalicStyle; + +/** + Returns if the web font style is normal. + */ @property(nonatomic) BOOL isNormalStyle; + +/** + Returns if the web font weight is semibold. + */ @property(nonatomic) BOOL isSemiboldWeight; +/** + Returns underlying font object. + @return The font + */ -(UIFont*)font; +/** + Tells the web font to update it's parameters from dictionary. + @param fontDict The dictionary to update from. + @param inheritedFont The font to inherit parameters from. + @return _YES_ if the update operation succeeded, _NO_ otherwise. + */ -(BOOL)updateWithDict:(NSDictionary *)fontDict inherits:(WebFont *)inheritedFont; +/** + Returns table row font. + @return The table row font. + */ +(WebFont *)tableRowFont; + +/** + Returns the default text font. + @return The default font. + */ +(WebFont *)defaultFont; + +/** + Returns the default bold font. + @return The default bold font. + */ +(WebFont *)defaultBoldFont; + +/** + Returns a web font by name. + @param name The web font name. + @return The web font. + */ +(WebFont *)fontWithName:(NSString*)name; @end diff --git a/iphone/Classes/Webcolor.h b/iphone/Classes/Webcolor.h index c5ab463847d..d9d5beccfac 100644 --- a/iphone/Classes/Webcolor.h +++ b/iphone/Classes/Webcolor.h @@ -7,14 +7,36 @@ #import +/** + The utility class for web colors. + */ @interface Webcolor : NSObject { } +(UIColor*)checkmarkColor; + +/** + Returns web color by name. + @param colorName The color name. + @return The color object. + */ +(UIColor*)webColorNamed:(NSString*)colorName; + +/** + Returns the color for RGB function. + @param functionString The RGB function string. + @return The color object. + */ +(UIColor*)colorForRGBFunction:(NSString*)functionString; + +/** + Returns teh color for hex string. + @param hexCode The hex string. + @return The color object. + */ +(UIColor*)colorForHex:(NSString*)hexCode; + +(void)flushCache; +(BOOL)isDarkColor:(UIColor*)color;