/SparkleShare/Mac/Growl.framework/Versions/A/Headers/GrowlDefines.h

http://github.com/hbons/SparkleShare · C++ Header · 348 lines · 45 code · 21 blank · 282 comment · 2 complexity · 5720559174a190f9819da1f39d932d58 MD5 · raw file

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