00001 /** 00002 00003 Appigo Third Party Integration - AppigoTask.h 00004 00005 Copyright (c) 2009-2010 Appigo, Inc. All rights reserved. 00006 00007 Permission is hereby granted, free of charge, to any person obtaining a copy 00008 of this software and associated documentation files (the "Software"), to 00009 deal in the Software without restriction, including without limitation the 00010 rights to use, copy, modify, merge, publish, distribute, sublicense, and/or 00011 sell copies of the Software, and to permit persons to whom the Software is 00012 furnished to do so, subject to the following conditions: 00013 00014 The above copyright notice and this permission notice shall be included in 00015 all copies or substantial portions of the Software. 00016 00017 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 00018 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 00019 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 00020 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 00021 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 00022 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS 00023 IN THE SOFTWARE. 00024 00025 */ 00026 00027 00028 /** 00029 @file AppigoTask.h 00030 @brief A class for representing an importable task. 00031 00032 @class AppigoTask AppigoNote.h 00033 @brief A class for representing an importable task. 00034 00035 A class to represent a task that can be placed on the Appigo Pasteboard and 00036 referenced by Appigo Applications. 00037 */ 00038 00039 00040 #import <Foundation/Foundation.h> 00041 00042 00043 @class AppigoNote; 00044 00045 00046 #define kAppigoTaskTypeAppIdKey @"app-id" 00047 #define kAppigoTaskTypeDisplayNameKey @"app-display-name" 00048 #define kAppigoTaskTypeCompletionNotifyUrlKey @"completion-notify-url" 00049 #define kAppigoTaskTypeCompletionLaunchUrlKey @"completion-launch-url" 00050 #define kAppigoTaskTypeActionLaunchURLKey @"action-launch-url" 00051 00052 00053 #pragma mark - 00054 #pragma mark Enums 00055 00056 00057 /** 00058 An enumeration of task priorities. 00059 */ 00060 typedef enum 00061 { 00062 AppigoTaskPriorityHigh = 1, 00063 AppigoTaskPriorityMedium, 00064 AppigoTaskPriorityLow, 00065 AppigoTaskPriorityNone 00066 } AppigoTaskPriority; 00067 00068 00069 /** 00070 An enumeration of task types. 00071 */ 00072 typedef enum 00073 { 00074 AppigoTaskTypeNormal = 0, 00075 AppigoTaskTypeProject, 00076 AppigoTaskTypeCallContact, 00077 AppigoTaskTypeSMSContact, 00078 AppigoTaskTypeEmailContact, 00079 AppigoTaskTypeVisitLocation, 00080 AppigoTaskTypeURL, 00081 AppigoTaskTypeChecklist, 00082 AppigoTaskTypeCustom // used for custom actions, see setActionForTask: 00083 } AppigoTaskType; 00084 00085 00086 #pragma mark - 00087 @interface AppigoTask : NSObject <NSCoding> 00088 { 00089 NSString *name; 00090 AppigoTaskType type; 00091 NSArray *typeKeys; 00092 NSArray *typeValues; 00093 AppigoTaskPriority priority; 00094 NSDate *dueDate; 00095 BOOL dueDateHasTime; 00096 NSDate *startDate; 00097 NSDate *completionDate; 00098 NSInteger repeat; 00099 NSString *advancedRepeat; 00100 NSString *note; 00101 NSString *list; 00102 NSString *context; 00103 NSString *tags; 00104 UIImage *actionImage; 00105 00106 NSMutableArray *_subtasks; 00107 } 00108 00109 00110 #pragma mark - 00111 #pragma mark Properties 00112 00113 /** The name of the task. */ 00114 @property (nonatomic, readonly) NSString *name; 00115 00116 /** 00117 The task type. If left unspecified, AppigoTaskTypeNormal will be used. 00118 */ 00119 00120 @property (nonatomic, readonly) AppigoTaskType type; 00121 00122 /** 00123 An array of keys (NSString *) with accompanying typeValues which specify 00124 additional type data information such as phone numbers, addresses, etc. which 00125 correspond to the task type. 00126 */ 00127 @property (nonatomic, readonly) NSArray *typeKeys; 00128 00129 /** An array of values (NSString *) corresponding to the typeKeys. */ 00130 @property (nonatomic, readonly) NSArray *typeValues; 00131 00132 /** An AppigoTaskPriority value to determine how important the task is. */ 00133 @property (nonatomic, assign) AppigoTaskPriority priority; 00134 00135 /** 00136 An NSDate specifying when the task is due. If you leave this nil, you are 00137 specifying that the task should not have a due date. 00138 */ 00139 @property (nonatomic, retain) NSDate *dueDate; 00140 00141 /** 00142 Specify YES when the dueDate contains specific information about the time that 00143 the task is due. 00144 */ 00145 @property (nonatomic, assign) BOOL dueDateHasTime; 00146 00147 /** 00148 An NSDate specifying when work for this task should begin to occur. 00149 This field is meant for compatibility with some synchronization options 00150 and may/may not be shown in the user interface in an Appigo application. 00151 */ 00152 @property (nonatomic, retain) NSDate *startDate; 00153 00154 /** 00155 An NSDate specifying when the task was completed. If the task is active 00156 and not completed, this should be left nil. 00157 */ 00158 @property (nonatomic, retain) NSDate *completionDate; 00159 00160 /** 00161 An integer value indicating whether the task should repeat. Specify 00162 0 to indicate that the task does not repeat. Other allowed values are: 00163 00164 Repeat from Due Date 00165 - 1 - Weekly 00166 - 2 - Monthly 00167 - 3 - Yearly 00168 - 4 - Daily 00169 - 5 - Bi-weekly 00170 - 6 - Bi-monthly 00171 - 7 - Semi-annually 00172 - 8 - Quarterly 00173 - 9 - Repeat with Parent 00174 - 50 - Advanced (look for additional information in the advanced repeat parameter) 00175 00176 Repeat from Completion Date 00177 - 101 - Weekly 00178 - 102 - Monthly 00179 - 103 - Yearly 00180 - 104 - Daily 00181 - 105 - Bi-weekly 00182 - 106 - Bi-monthly 00183 - 107 - Semi-annually 00184 - 108 - Quarterly 00185 - 109 - Repeat with Parent 00186 - 150 - Advanced (look for additional information in the advanced repeat parameter) 00187 */ 00188 @property (nonatomic, assign) NSInteger repeat; 00189 00190 /** 00191 A string which contains advance repeat information. 00192 00193 Valid strings should conform to one of the following formats: 00194 - Every X <days, weeks, months, years> 00195 - Every <Monday, Tuesday...Sunday, Weekday, Weekend> 00196 - On the X <Monday...Sunday> of the month 00197 */ 00198 @property (nonatomic, retain) NSString *advancedRepeat; 00199 00200 /** 00201 A string of supporting information about the task. 00202 */ 00203 @property (nonatomic, retain) NSString *note; 00204 00205 /** 00206 A case-insensitive list name that the task belongs to. If a matching 00207 list is found in Todo the task will be placed inside the corresponding 00208 list. If multiple lists with the same name exist in Todo, the list 00209 used for this task is undefined. If a matching list name is not found 00210 in Todo, the list will be created before assigning the task to the list. 00211 */ 00212 @property (nonatomic, retain) NSString *list; 00213 00214 /** 00215 A case-insensitive context name that the task should be associated with. 00216 If a matching context is found in Todo, the context will be used. If no 00217 existing context is found, the specified context will be created. 00218 */ 00219 @property (nonatomic, retain) NSString *context; 00220 00221 /** 00222 A comma-separated list of tags to associate with the task. Non-existing 00223 tags will be created. 00224 */ 00225 @property (nonatomic, retain) NSString *tags; 00226 00227 /** 00228 The action image associated with a custom task type. See the 00229 @ref pageCustomTaskType "Custom Task Types" page for more information. 00230 */ 00231 @property (nonatomic, retain) UIImage *actionImage; 00232 00233 /** 00234 An array of tasks that are the subtasks of a project or checklist type. If 00235 the task type is not set as Project/Checklist, any specified subtasks will be 00236 discarded when imported to Todo. 00237 */ 00238 @property (nonatomic, copy) NSArray *subtasks; 00239 00240 00241 #pragma mark - 00242 #pragma mark Methods 00243 00244 00245 /** 00246 Initialize a new task object. 00247 00248 @param taskName The task name. The name will be trimmed of whitespace (an 00249 empty name is invalid and will be replaced with, "Unknown"). 00250 */ 00251 - (id)initWithName:(NSString *)taskName; 00252 00253 00254 /** 00255 Set the task type. 00256 00257 All task types except for Normal, Project, and Checklist must have 00258 corresponding keys and values set for additional task type information. This 00259 information will eventually be used to present phone numbers to a user such as 00260 "mobile: 555-555-1234" for a Call a Contact task type. The keys and values will 00261 be ignored when setting task types of AppigoTaskTypeNormal, 00262 AppigoTaskTypeProject, and AppigoTaskTypeChecklist. 00263 00264 For more information about task type data (the property keys and values, refer 00265 to the @ref pageTaskTypeData "Task Type Data" page. 00266 00267 @param aTaskType The new task type. 00268 @param keys An array of keys (NSString *) that match up with the number of 00269 values. These keys specify additional task type information such as phone 00270 numbers, addresses, urls, etc. that will be shown to the user when they tap 00271 a task's action button in Todo (to call a contact, visit a website, etc.). 00272 @param values An array of values which match up with the number of keys. The 00273 values will be items such as phone numbers, email addresses, addresses, etc. 00274 */ 00275 - (void)setType:(AppigoTaskType)aTaskType withPropertyKeys:(NSArray *)keys withPropertyValues:(NSArray *)values; 00276 00277 /** 00278 A convenience method to add a subtask to the task. You should only add subtasks 00279 to projects or checklists. Subtasks added to other types of tasks will be 00280 ignored by Todo if you attempt to import them. 00281 00282 @param subtask The subtask to add. 00283 */ 00284 - (void)addSubtask:(AppigoTask *)subtask; 00285 00286 00287 /** 00288 Add a custom action to the task which will allow custom actions on the task 00289 once it is imported into Appigo Todo. An overview of this process is described 00290 on the @ref pageCustomTaskType "Custom Task Types" page. 00291 00292 Set an option action that will be used when importing a task in Todo. This 00293 allows third party applications to be notified/called when the user completes 00294 the task or when they perform the task type's "action" (just like calling a 00295 contact on the Call Contact task). You must specify at least one of the URLs 00296 in the parameters. If you do not specify any URLs, this call will do nothing. 00297 00298 Be aware that custom task information (name, URLs, etc.) is stored in the 00299 task's typeData and the existing type and typeData information will be 00300 replaced with the information in this method. 00301 00302 @note Calling this method multiple times on the same task will replace the 00303 previously set action. 00304 00305 @param aDisplayName (required) A string that will be used to show the origin 00306 of the custom task in Todo. This string is used regardless of the device's 00307 language/locale/region settings. 00308 00309 @param aCompletionNotifyURL (optional) A URL which specifies a call to a backend 00310 service you may operate. If specified, a UIAlertView will ask the user if they 00311 want to notify appDisplayName that they are completing the task. This URL 00312 should reference a service available on the Internet and not your iPhone app 00313 (use completionLaunchURL to launch your application when a task is completed). 00314 00315 @param aCompletionLaunchURL (optional) A URL which can be used to launch your 00316 iPhone app when a user completes the task. A UIAlertView will ask the user if 00317 they want to launch appDisplayName. 00318 00319 @param anActionLaunchURL (optional) A URL which will be used to perform an action 00320 from the task's detail screen. A UIAlertView will ask the user if they want to 00321 open appDisplayName before calling openURL: on this URL. 00322 00323 @param anActionImage (optional) This image will be used on the task's detail 00324 screen to the left of the task's name and should be drawn to mimic Todo's 00325 built-in action buttons, which are typically round and should appear to look 00326 like a button. For an example of this, create a "Call a Contact" task and then 00327 look at the icon which appears to the left of the task name. 00328 The size of this image must be 29x29 pixels and should be drawn using a 00329 transparent background. The image will be transferred to Todo as 00330 NSData * using UIImagePNGRepresentation(). If 00331 UIImagePNGRepresentation() returns nil, a default action image will be 00332 used. Action Images are tied to a specific application ID. If you specify a 00333 different image than previous imports, the most recently imported image 00334 will be used for all previous imported tasks made from your application. 00335 actionLaunchURL must also be specified if you specify this image. If 00336 actionLaunchURL is nil, the actionImage will be ignored. 00337 00338 */ 00339 - (void)setActionForTaskWithAppDisplayName:(NSString *)aDisplayName 00340 withCompletionNotifyURL:(NSURL *)aCompletionNotifyURL 00341 withCompletionLaunchURL:(NSURL *)aCompletionLaunchURL 00342 withActionLaunchURL:(NSURL *)anActionLaunchURL 00343 withActionImage:(UIImage *)anActionImage; 00344 00345 00346 /** 00347 Get a plain text representation of a task. 00348 00349 @param includeName Specify YES to include the name in the text representation 00350 or NO to omit it. 00351 @return Returns a plain text representation of the task. 00352 */ 00353 - (NSString *)plainTextRepresentationWithName:(BOOL)includeName; 00354 00355 00356 /** 00357 Build an AppigoNote object from the task that can be used to import the task 00358 into Appigo Notebook. 00359 00360 @return Returns an AppigoNote object. 00361 */ 00362 - (AppigoNote *)noteRepresentation; 00363 00364 @end