1// 2// GrowlDefines.h 3// 4 5#ifndef _GROWLDEFINES_H 6#define _GROWLDEFINES_H 7 8#ifdef __OBJC__ 9#define XSTR(x) (@x) 10#else 11#define XSTR CFSTR 12#endif 13 14/*! @header GrowlDefines.h 15 * @abstract Defines all the notification keys. 16 * @discussion Defines all the keys used for registration with Growl and for 17 * Growl notifications. 18 * 19 * Most applications should use the functions or methods of Growl.framework 20 * instead of posting notifications such as those described here. 21 * @updated 2004-01-25 22 */ 23 24// UserInfo Keys for Registration 25#pragma mark UserInfo Keys for Registration 26 27/*! @group Registration userInfo keys */ 28/* @abstract Keys for the userInfo dictionary of a GROWL_APP_REGISTRATION distributed notification. 29 * @discussion The values of these keys describe the application and the 30 * notifications it may post. 31 * 32 * Your application must register with Growl before it can post Growl 33 * notifications (and have them not be ignored). However, as of Growl 0.6, 34 * posting GROWL_APP_REGISTRATION notifications directly is no longer the 35 * preferred way to register your application. Your application should instead 36 * use Growl.framework's delegate system. 37 * See +[GrowlApplicationBridge setGrowlDelegate:] or Growl_SetDelegate for 38 * more information. 39 */ 40 41/*! @defined GROWL_APP_NAME 42 * @abstract The name of your application. 43 * @discussion The name of your application. This should remain stable between 44 * different versions and incarnations of your application. 45 * For example, "SurfWriter" is a good app name, whereas "SurfWriter 2.0" and 46 * "SurfWriter Lite" are not. 47 */ 48#define GROWL_APP_NAME XSTR("ApplicationName") 49/*! @defined GROWL_APP_ID 50 * @abstract The bundle identifier of your application. 51 * @discussion The bundle identifier of your application. This key should 52 * be unique for your application while there may be several applications 53 * with the same GROWL_APP_NAME. 54 * This key is optional. 55 */ 56#define GROWL_APP_ID XSTR("ApplicationId") 57/*! @defined GROWL_APP_ICON_DATA 58 * @abstract The image data for your application's icon. 59 * @discussion Image data representing your application's icon. This may be 60 * superimposed on a notification icon as a badge, used as the notification 61 * icon when a notification-specific icon is not supplied, or ignored 62 * altogether, depending on the display. Must be in a format supported by 63 * NSImage, such as TIFF, PNG, GIF, JPEG, BMP, PICT, or PDF. 64 * 65 * Optional. Not supported by all display plugins. 66 */ 67#define GROWL_APP_ICON_DATA XSTR("ApplicationIcon") 68/*! @defined GROWL_NOTIFICATIONS_DEFAULT 69 * @abstract The array of notifications to turn on by default. 70 * @discussion These are the names of the notifications that should be enabled 71 * by default when your application registers for the first time. If your 72 * application reregisters, Growl will look here for any new notification 73 * names found in GROWL_NOTIFICATIONS_ALL, but ignore any others. 74 */ 75#define GROWL_NOTIFICATIONS_DEFAULT XSTR("DefaultNotifications") 76/*! @defined GROWL_NOTIFICATIONS_ALL 77 * @abstract The array of all notifications your application can send. 78 * @discussion These are the names of all of the notifications that your 79 * application may post. See GROWL_NOTIFICATION_NAME for a discussion of good 80 * notification names. 81 */ 82#define GROWL_NOTIFICATIONS_ALL XSTR("AllNotifications") 83/*! @defined GROWL_NOTIFICATIONS_HUMAN_READABLE_DESCRIPTIONS 84 * @abstract A dictionary of human-readable names for your notifications. 85 * @discussion By default, the Growl UI will display notifications by the names given in GROWL_NOTIFICATIONS_ALL 86 * which correspond to the GROWL_NOTIFICATION_NAME. This dictionary specifies the human-readable name to display. 87 * The keys of the dictionary are GROWL_NOTIFICATION_NAME strings; the objects are the human-readable versions. 88 * For any GROWL_NOTIFICATION_NAME not specific in this dictionary, the GROWL_NOTIFICATION_NAME will be displayed. 89 * 90 * This key is optional. 91 */ 92#define GROWL_NOTIFICATIONS_HUMAN_READABLE_NAMES XSTR("HumanReadableNames") 93/*! @defined GROWL_NOTIFICATIONS_DESCRIPTIONS 94* @abstract A dictionary of descriptions of _when_ each notification occurs 95* @discussion This is an NSDictionary whose keys are GROWL_NOTIFICATION_NAME strings and whose objects are 96* descriptions of _when_ each notification occurs, such as "You received a new mail message" or 97* "A file finished downloading". 98* 99* This key is optional. 100*/ 101#define GROWL_NOTIFICATIONS_DESCRIPTIONS XSTR("NotificationDescriptions") 102 103/*! @defined GROWL_TICKET_VERSION 104 * @abstract The version of your registration ticket. 105 * @discussion Include this key in a ticket plist file that you put in your 106 * application bundle for auto-discovery. The current ticket version is 1. 107 */ 108#define GROWL_TICKET_VERSION XSTR("TicketVersion") 109// UserInfo Keys for Notifications 110#pragma mark UserInfo Keys for Notifications 111 112/*! @group Notification userInfo keys */ 113/* @abstract Keys for the userInfo dictionary of a GROWL_NOTIFICATION distributed notification. 114 * @discussion The values of these keys describe the content of a Growl 115 * notification. 116 * 117 * Not all of these keys are supported by all displays. Only the name, title, 118 * and description of a notification are universal. Most of the built-in 119 * displays do support all of these keys, and most other visual displays 120 * probably will also. But, as of 0.6, the Log, MailMe, and Speech displays 121 * support only textual data. 122 */ 123 124/*! @defined GROWL_NOTIFICATION_NAME 125 * @abstract The name of the notification. 126 * @discussion The name of the notification. Note that if you do not define 127 * GROWL_NOTIFICATIONS_HUMAN_READABLE_NAMES when registering your ticket originally this name 128 * will the one displayed within the Growl preference pane and should be human-readable. 129 */ 130#define GROWL_NOTIFICATION_NAME XSTR("NotificationName") 131/*! @defined GROWL_NOTIFICATION_TITLE 132 * @abstract The title to display in the notification. 133 * @discussion The title of the notification. Should be very brief. 134 * The title usually says what happened, e.g. "Download complete". 135 */ 136#define GROWL_NOTIFICATION_TITLE XSTR("NotificationTitle") 137/*! @defined GROWL_NOTIFICATION_DESCRIPTION 138 * @abstract The description to display in the notification. 139 * @discussion The description should be longer and more verbose than the title. 140 * The description usually tells the subject of the action, 141 * e.g. "Growl-0.6.dmg downloaded in 5.02 minutes". 142 */ 143#define GROWL_NOTIFICATION_DESCRIPTION XSTR("NotificationDescription") 144/*! @defined GROWL_NOTIFICATION_ICON 145 * @discussion Image data for the notification icon. Image data must be in a format 146 * supported by NSImage, such as TIFF, PNG, GIF, JPEG, BMP, PICT, or PDF. 147 * 148 * Optional. Not supported by all display plugins. 149 */ 150#define GROWL_NOTIFICATION_ICON_DATA XSTR("NotificationIcon") 151/*! @defined GROWL_NOTIFICATION_APP_ICON 152 * @discussion Image data for the application icon, in case GROWL_APP_ICON does 153 * not apply for some reason. Image data be in a format supported by NSImage, such 154 * as TIFF, PNG, GIF, JPEG, BMP, PICT, or PDF. 155 * 156 * Optional. Not supported by all display plugins. 157 */ 158#define GROWL_NOTIFICATION_APP_ICON_DATA XSTR("NotificationAppIcon") 159/*! @defined GROWL_NOTIFICATION_PRIORITY 160 * @discussion The priority of the notification as an integer number from 161 * -2 to +2 (+2 being highest). 162 * 163 * Optional. Not supported by all display plugins. 164 */ 165#define GROWL_NOTIFICATION_PRIORITY XSTR("NotificationPriority") 166/*! @defined GROWL_NOTIFICATION_STICKY 167 * @discussion A Boolean number controlling whether the notification is sticky. 168 * 169 * Optional. Not supported by all display plugins. 170 */ 171#define GROWL_NOTIFICATION_STICKY XSTR("NotificationSticky") 172/*! @defined GROWL_NOTIFICATION_CLICK_CONTEXT 173 * @abstract Identifies which notification was clicked. 174 * @discussion An identifier for the notification for clicking purposes. 175 * 176 * This will be passed back to the application when the notification is 177 * clicked. It must be plist-encodable (a data, dictionary, array, number, or 178 * string object), and it should be unique for each notification you post. 179 * A good click context would be a UUID string returned by NSProcessInfo or 180 * CFUUID. 181 * 182 * Optional. Not supported by all display plugins. 183 */ 184#define GROWL_NOTIFICATION_CLICK_CONTEXT XSTR("NotificationClickContext") 185 186/*! @defined GROWL_NOTIFICATION_IDENTIFIER 187 * @abstract An identifier for the notification for coalescing purposes. 188 * Notifications with the same identifier fall into the same class; only 189 * the last notification of a class is displayed on the screen. If a 190 * notification of the same class is currently being displayed, it is 191 * replaced by this notification. 192 * 193 * Optional. Not supported by all display plugins. 194 */ 195#define GROWL_NOTIFICATION_IDENTIFIER XSTR("GrowlNotificationIdentifier") 196 197/*! @defined GROWL_APP_PID 198 * @abstract The process identifier of the process which sends this 199 * notification. If this field is set, the application will only receive 200 * clicked and timed out notifications which originate from this process. 201 * 202 * Optional. 203 */ 204#define GROWL_APP_PID XSTR("ApplicationPID") 205 206/*! @defined GROWL_NOTIFICATION_PROGRESS 207* @abstract If this key is set, it should contain a double value wrapped 208* in a NSNumber which describes some sort of progress (from 0.0 to 100.0). 209* If this is key is not set, no progress bar is shown. 210* 211* Optional. Not supported by all display plugins. 212*/ 213#define GROWL_NOTIFICATION_PROGRESS XSTR("NotificationProgress") 214 215// Notifications 216#pragma mark Notifications 217 218/*! @group Notification names */ 219/* @abstract Names of distributed notifications used by Growl. 220 * @discussion These are notifications used by applications (directly or 221 * indirectly) to interact with Growl, and by Growl for interaction between 222 * its components. 223 * 224 * Most of these should no longer be used in Growl 0.6 and later, in favor of 225 * Growl.framework's GrowlApplicationBridge APIs. 226 */ 227 228/*! @defined GROWL_APP_REGISTRATION 229 * @abstract The distributed notification for registering your application. 230 * @discussion This is the name of the distributed notification that can be 231 * used to register applications with Growl. 232 * 233 * The userInfo dictionary for this notification can contain these keys: 234 * <ul> 235 * <li>GROWL_APP_NAME</li> 236 * <li>GROWL_APP_ICON_DATA</li> 237 * <li>GROWL_NOTIFICATIONS_ALL</li> 238 * <li>GROWL_NOTIFICATIONS_DEFAULT</li> 239 * </ul> 240 * 241 * No longer recommended as of Growl 0.6. An alternate method of registering 242 * is to use Growl.framework's delegate system. 243 * See +[GrowlApplicationBridge setGrowlDelegate:] or Growl_SetDelegate for 244 * more information. 245 */ 246#define GROWL_APP_REGISTRATION XSTR("GrowlApplicationRegistrationNotification") 247/*! @defined GROWL_APP_REGISTRATION_CONF 248 * @abstract The distributed notification for confirming registration. 249 * @discussion The name of the distributed notification sent to confirm the 250 * registration. Used by the Growl preference pane. Your application probably 251 * does not need to use this notification. 252 */ 253#define GROWL_APP_REGISTRATION_CONF XSTR("GrowlApplicationRegistrationConfirmationNotification") 254/*! @defined GROWL_NOTIFICATION 255 * @abstract The distributed notification for Growl notifications. 256 * @discussion This is what it all comes down to. This is the name of the 257 * distributed notification that your application posts to actually send a 258 * Growl notification. 259 * 260 * The userInfo dictionary for this notification can contain these keys: 261 * <ul> 262 * <li>GROWL_NOTIFICATION_NAME (required)</li> 263 * <li>GROWL_NOTIFICATION_TITLE (required)</li> 264 * <li>GROWL_NOTIFICATION_DESCRIPTION (required)</li> 265 * <li>GROWL_NOTIFICATION_ICON</li> 266 * <li>GROWL_NOTIFICATION_APP_ICON</li> 267 * <li>GROWL_NOTIFICATION_PRIORITY</li> 268 * <li>GROWL_NOTIFICATION_STICKY</li> 269 * <li>GROWL_NOTIFICATION_CLICK_CONTEXT</li> 270 * <li>GROWL_APP_NAME (required)</li> 271 * </ul> 272 * 273 * No longer recommended as of Growl 0.6. Three alternate methods of posting 274 * notifications are +[GrowlApplicationBridge notifyWithTitle:description:notificationName:iconData:priority:isSticky:clickContext:], 275 * Growl_NotifyWithTitleDescriptionNameIconPriorityStickyClickContext, and 276 * Growl_PostNotification. 277 */ 278#define GROWL_NOTIFICATION XSTR("GrowlNotification") 279/*! @defined GROWL_PING 280 * @abstract A distributed notification to check whether Growl is running. 281 * @discussion This is used by the Growl preference pane. If it receives a 282 * GROWL_PONG, the preference pane takes this to mean that Growl is running. 283 */ 284#define GROWL_PING XSTR("Honey, Mind Taking Out The Trash") 285/*! @defined GROWL_PONG 286 * @abstract The distributed notification sent in reply to GROWL_PING. 287 * @discussion GrowlHelperApp posts this in reply to GROWL_PING. 288 */ 289#define GROWL_PONG XSTR("What Do You Want From Me, Woman") 290/*! @defined GROWL_IS_READY 291 * @abstract The distributed notification sent when Growl starts up. 292 * @discussion GrowlHelperApp posts this when it has begin listening on all of 293 * its sources for new notifications. GrowlApplicationBridge (in 294 * Growl.framework), upon receiving this notification, reregisters using the 295 * registration dictionary supplied by its delegate. 296 */ 297#define GROWL_IS_READY XSTR("Lend Me Some Sugar; I Am Your Neighbor!") 298 299 300/*! @defined GROWL_DISTRIBUTED_NOTIFICATION_CLICKED_SUFFIX 301 * @abstract Part of the name of the distributed notification sent when a supported notification is clicked. 302 * @discussion When a Growl notification with a click context is clicked on by 303 * the user, Growl posts a distributed notification whose name is in the format: 304 * [NSString stringWithFormat:@"%@-%d-%@", appName, pid, GROWL_DISTRIBUTED_NOTIFICATION_CLICKED_SUFFIX] 305 * The GrowlApplicationBridge responds to this notification by calling a callback in its delegate. 306 */ 307#define GROWL_DISTRIBUTED_NOTIFICATION_CLICKED_SUFFIX XSTR("GrowlClicked!") 308 309/*! @defined GROWL_DISTRIBUTED_NOTIFICATION_TIMED_OUT_SUFFIX 310 * @abstract Part of the name of the distributed notification sent when a supported notification times out without being clicked. 311 * @discussion When a Growl notification with a click context times out, Growl posts a distributed notification 312 * whose name is in the format: 313 * [NSString stringWithFormat:@"%@-%d-%@", appName, pid, GROWL_DISTRIBUTED_NOTIFICATION_TIMED_OUT_SUFFIX] 314 * The GrowlApplicationBridge responds to this notification by calling a callback in its delegate. 315 * NOTE: The user may have actually clicked the 'close' button; this triggers an *immediate* time-out of the notification. 316 */ 317#define GROWL_DISTRIBUTED_NOTIFICATION_TIMED_OUT_SUFFIX XSTR("GrowlTimedOut!") 318 319/*! @group Other symbols */ 320/* Symbols which don't fit into any of the other categories. */ 321 322/*! @defined GROWL_KEY_CLICKED_CONTEXT 323 * @abstract Used internally as the key for the clickedContext passed over DNC. 324 * @discussion This key is used in GROWL_NOTIFICATION_CLICKED, and contains the 325 * click context that was supplied in the original notification. 326 */ 327#define GROWL_KEY_CLICKED_CONTEXT XSTR("ClickedContext") 328/*! @defined GROWL_REG_DICT_EXTENSION 329 * @abstract The filename extension for registration dictionaries. 330 * @discussion The GrowlApplicationBridge in Growl.framework registers with 331 * Growl by creating a file with the extension of .(GROWL_REG_DICT_EXTENSION) 332 * and opening it in the GrowlHelperApp. This happens whether or not Growl is 333 * running; if it was stopped, it quits immediately without listening for 334 * notifications. 335 */ 336#define GROWL_REG_DICT_EXTENSION XSTR("growlRegDict") 337 338 339#define GROWL_POSITION_PREFERENCE_KEY @"GrowlSelectedPosition" 340 341#endif //ndef _GROWLDEFINES_H 342