GrowlDefines.h

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