source: trunk/macosx/Growl.framework/Versions/A/Headers/GrowlDefines.h @ 13469

Last change on this file since 13469 was 13469, checked in by livings124, 10 years ago

Revert r13468 for now.

File size: 17.7 KB
Line 
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/*! @defined GROWL_NOTIFICATIONS_ICONS
103 *  @abstract A dictionary of icons for each notification
104 *  @discussion This is an NSDictionary whose keys are GROWL_NOTIFICATION_NAME strings and whose objects are
105 *  icons for each notification, for GNTP spec
106 *
107 *  This key is optional.
108 */
109#define GROWL_NOTIFICATIONS_ICONS XSTR("NotificationIcons")
110
111/*!     @defined        GROWL_TICKET_VERSION
112 *      @abstract       The version of your registration ticket.
113 *      @discussion     Include this key in a ticket plist file that you put in your
114 *       application bundle for auto-discovery. The current ticket version is 1.
115 */
116#define GROWL_TICKET_VERSION                    XSTR("TicketVersion")
117// UserInfo Keys for Notifications
118#pragma mark UserInfo Keys for Notifications
119
120/*!     @group Notification userInfo keys */
121/*      @abstract       Keys for the userInfo dictionary of a GROWL_NOTIFICATION distributed notification.
122 *      @discussion The values of these keys describe the content of a Growl
123 *       notification.
124 *
125 *       Not all of these keys are supported by all displays. Only the name, title,
126 *       and description of a notification are universal. Most of the built-in
127 *       displays do support all of these keys, and most other visual displays
128 *       probably will also. But, as of 0.6, the Log, MailMe, and Speech displays
129 *       support only textual data.
130 */
131
132/*!     @defined GROWL_NOTIFICATION_NAME
133 *      @abstract The name of the notification.
134 *      @discussion The name of the notification. Note that if you do not define
135 *  GROWL_NOTIFICATIONS_HUMAN_READABLE_NAMES when registering your ticket originally this name
136 *  will the one displayed within the Growl preference pane and should be human-readable.
137 */
138#define GROWL_NOTIFICATION_NAME                 XSTR("NotificationName")
139/*!     @defined GROWL_NOTIFICATION_TITLE
140 *      @abstract The title to display in the notification.
141 *      @discussion The title of the notification. Should be very brief.
142 *       The title usually says what happened, e.g. "Download complete".
143 */
144#define GROWL_NOTIFICATION_TITLE                XSTR("NotificationTitle")
145/*!     @defined GROWL_NOTIFICATION_DESCRIPTION
146 *      @abstract The description to display in the notification.
147 *      @discussion The description should be longer and more verbose than the title.
148 *       The description usually tells the subject of the action,
149 *       e.g. "Growl-0.6.dmg downloaded in 5.02 minutes".
150 */
151#define GROWL_NOTIFICATION_DESCRIPTION          XSTR("NotificationDescription")
152/*!     @defined GROWL_NOTIFICATION_ICON
153 *      @discussion Image data for the notification icon. Image data must be in a format
154 *       supported by NSImage, such as TIFF, PNG, GIF, JPEG, BMP, PICT, or PDF.
155 *
156 *       Optional. Not supported by all display plugins.
157 */
158#define GROWL_NOTIFICATION_ICON_DATA                    XSTR("NotificationIcon")
159/*!     @defined GROWL_NOTIFICATION_APP_ICON
160 *      @discussion Image data for the application icon, in case GROWL_APP_ICON does
161 *       not apply for some reason. Image data be in a format supported by NSImage, such
162 *       as TIFF, PNG, GIF, JPEG, BMP, PICT, or PDF.
163 *
164 *       Optional. Not supported by all display plugins.
165 */
166#define GROWL_NOTIFICATION_APP_ICON_DATA                XSTR("NotificationAppIcon")
167/*!     @defined GROWL_NOTIFICATION_PRIORITY
168 *      @discussion The priority of the notification as an integer number from
169 *       -2 to +2 (+2 being highest).
170 *
171 *       Optional. Not supported by all display plugins.
172 */
173#define GROWL_NOTIFICATION_PRIORITY             XSTR("NotificationPriority")
174/*!     @defined GROWL_NOTIFICATION_STICKY
175 *      @discussion A Boolean number controlling whether the notification is sticky.
176 *
177 *       Optional. Not supported by all display plugins.
178 */
179#define GROWL_NOTIFICATION_STICKY               XSTR("NotificationSticky")
180/*!     @defined GROWL_NOTIFICATION_CLICK_CONTEXT
181 *      @abstract Identifies which notification was clicked.
182 *      @discussion An identifier for the notification for clicking purposes.
183 *
184 *       This will be passed back to the application when the notification is
185 *       clicked. It must be plist-encodable (a data, dictionary, array, number, or
186 *       string object), and it should be unique for each notification you post.
187 *       A good click context would be a UUID string returned by NSProcessInfo or
188 *       CFUUID.
189 *
190 *       Optional. Not supported by all display plugins.
191 */
192#define GROWL_NOTIFICATION_CLICK_CONTEXT                        XSTR("NotificationClickContext")
193
194/*!     @defined GROWL_NOTIFICATION_IDENTIFIER
195 *      @abstract An identifier for the notification for coalescing purposes.
196 *   Notifications with the same identifier fall into the same class; only
197 *   the last notification of a class is displayed on the screen. If a
198 *   notification of the same class is currently being displayed, it is
199 *   replaced by this notification.
200 *
201 *       Optional. Not supported by all display plugins.
202 */
203#define GROWL_NOTIFICATION_IDENTIFIER   XSTR("GrowlNotificationIdentifier")
204
205/*!     @defined GROWL_APP_PID
206 *      @abstract The process identifier of the process which sends this
207 *   notification. If this field is set, the application will only receive
208 *   clicked and timed out notifications which originate from this process.
209 *
210 *       Optional.
211 */
212#define GROWL_APP_PID                                   XSTR("ApplicationPID")
213
214/*!     @defined GROWL_NOTIFICATION_PROGRESS
215*       @abstract If this key is set, it should contain a double value wrapped
216*     in a NSNumber which describes some sort of progress (from 0.0 to 100.0).
217*     If this is key is not set, no progress bar is shown.
218*
219*        Optional. Not supported by all display plugins.
220*/
221#define GROWL_NOTIFICATION_PROGRESS             XSTR("NotificationProgress")
222
223/*!     @defined GROWL_NOTIFICATION_ALREADY_SHOWN
224 *      @abstract If this key is set, it should contain a bool value wrapped
225 *   in a NSNumber which describes whether the notification has
226 *   already been displayed, for instance by built in Notification
227 *   Center support.  This value can be used to allow display
228 *   plugins to skip a notification, while still allowing Growl
229 *   actions to run on them.
230 *
231 *       Optional. Not supported by all display plugins.
232 */
233#define GROWL_NOTIFICATION_ALREADY_SHOWN                XSTR("AlreadyShown")
234
235
236// Notifications
237#pragma mark Notifications
238
239/*!     @group Notification names */
240/*      @abstract       Names of distributed notifications used by Growl.
241 *      @discussion     These are notifications used by applications (directly or
242 *       indirectly) to interact with Growl, and by Growl for interaction between
243 *       its components.
244 *
245 *       Most of these should no longer be used in Growl 0.6 and later, in favor of
246 *       Growl.framework's GrowlApplicationBridge APIs.
247 */
248
249/*!     @defined GROWL_APP_REGISTRATION
250 *      @abstract The distributed notification for registering your application.
251 *      @discussion This is the name of the distributed notification that can be
252 *       used to register applications with Growl.
253 *
254 *       The userInfo dictionary for this notification can contain these keys:
255 *       <ul>
256 *              <li>GROWL_APP_NAME</li>
257 *              <li>GROWL_APP_ICON_DATA</li>
258 *              <li>GROWL_NOTIFICATIONS_ALL</li>
259 *              <li>GROWL_NOTIFICATIONS_DEFAULT</li>
260 *       </ul>
261 *
262 *       No longer recommended as of Growl 0.6. An alternate method of registering
263 *       is to use Growl.framework's delegate system.
264 *       See +[GrowlApplicationBridge setGrowlDelegate:] or Growl_SetDelegate for
265 *       more information.
266 */
267#define GROWL_APP_REGISTRATION                  XSTR("GrowlApplicationRegistrationNotification")
268/*!     @defined GROWL_APP_REGISTRATION_CONF
269 *      @abstract The distributed notification for confirming registration.
270 *      @discussion The name of the distributed notification sent to confirm the
271 *       registration. Used by the Growl preference pane. Your application probably
272 *       does not need to use this notification.
273 */
274#define GROWL_APP_REGISTRATION_CONF             XSTR("GrowlApplicationRegistrationConfirmationNotification")
275/*!     @defined GROWL_NOTIFICATION
276 *      @abstract The distributed notification for Growl notifications.
277 *      @discussion This is what it all comes down to. This is the name of the
278 *       distributed notification that your application posts to actually send a
279 *       Growl notification.
280 *
281 *       The userInfo dictionary for this notification can contain these keys:
282 *       <ul>
283 *              <li>GROWL_NOTIFICATION_NAME (required)</li>
284 *              <li>GROWL_NOTIFICATION_TITLE (required)</li>
285 *              <li>GROWL_NOTIFICATION_DESCRIPTION (required)</li>
286 *              <li>GROWL_NOTIFICATION_ICON</li>
287 *              <li>GROWL_NOTIFICATION_APP_ICON</li>
288 *              <li>GROWL_NOTIFICATION_PRIORITY</li>
289 *              <li>GROWL_NOTIFICATION_STICKY</li>
290 *              <li>GROWL_NOTIFICATION_CLICK_CONTEXT</li>
291 *              <li>GROWL_APP_NAME (required)</li>
292 *       </ul>
293 *
294 *       No longer recommended as of Growl 0.6. Three alternate methods of posting
295 *       notifications are +[GrowlApplicationBridge notifyWithTitle:description:notificationName:iconData:priority:isSticky:clickContext:],
296 *       Growl_NotifyWithTitleDescriptionNameIconPriorityStickyClickContext, and
297 *       Growl_PostNotification.
298 */
299#define GROWL_NOTIFICATION                              XSTR("GrowlNotification")
300/*!     @defined GROWL_PING
301 *      @abstract A distributed notification to check whether Growl is running.
302 *      @discussion This is used by the Growl preference pane. If it receives a
303 *       GROWL_PONG, the preference pane takes this to mean that Growl is running.
304 */
305#define GROWL_PING                                              XSTR("Honey, Mind Taking Out The Trash")
306/*!     @defined GROWL_PONG
307 *      @abstract The distributed notification sent in reply to GROWL_PING.
308 *      @discussion GrowlHelperApp posts this in reply to GROWL_PING.
309 */
310#define GROWL_PONG                                              XSTR("What Do You Want From Me, Woman")
311/*!     @defined GROWL_IS_READY
312 *      @abstract The distributed notification sent when Growl starts up.
313 *      @discussion GrowlHelperApp posts this when it has begin listening on all of
314 *       its sources for new notifications. GrowlApplicationBridge (in
315 *       Growl.framework), upon receiving this notification, reregisters using the
316 *       registration dictionary supplied by its delegate.
317 */
318#define GROWL_IS_READY                                  XSTR("Lend Me Some Sugar; I Am Your Neighbor!")
319
320
321/*!     @defined GROWL_DISTRIBUTED_NOTIFICATION_CLICKED_SUFFIX
322 *      @abstract Part of the name of the distributed notification sent when a supported notification is clicked.
323 *      @discussion When a Growl notification with a click context is clicked on by
324 *       the user, Growl posts a distributed notification whose name is in the format:
325 *        [NSString stringWithFormat:@"%@-%d-%@", appName, pid, GROWL_DISTRIBUTED_NOTIFICATION_CLICKED_SUFFIX]
326 *       The GrowlApplicationBridge responds to this notification by calling a callback in its delegate.
327 */
328#define GROWL_DISTRIBUTED_NOTIFICATION_CLICKED_SUFFIX           XSTR("GrowlClicked!")
329
330/*!     @defined GROWL_DISTRIBUTED_NOTIFICATION_TIMED_OUT_SUFFIX
331 *      @abstract Part of the name of the distributed notification sent when a supported notification times out without being clicked.
332 *      @discussion When a Growl notification with a click context times out, Growl posts a distributed notification
333 *       whose name is in the format:
334 *                [NSString stringWithFormat:@"%@-%d-%@", appName, pid, GROWL_DISTRIBUTED_NOTIFICATION_TIMED_OUT_SUFFIX]
335 *       The GrowlApplicationBridge responds to this notification by calling a callback in its delegate.
336 *   NOTE: The user may have actually clicked the 'close' button; this triggers an *immediate* time-out of the notification.
337 */
338#define GROWL_DISTRIBUTED_NOTIFICATION_TIMED_OUT_SUFFIX         XSTR("GrowlTimedOut!")
339
340/*!     @defined GROWL_DISTRIBUTED_NOTIFICATION_NOTIFICATIONCENTER_ON
341 *      @abstract The distributed notification sent when the Notification Center support is toggled on in Growl 2.0
342 *      @discussion When the user enables Notification Center support in Growl 2.0, this notification is sent
343 *      to inform all running apps that they should now speak to Notification Center directly.
344 */
345#define GROWL_DISTRIBUTED_NOTIFICATION_NOTIFICATIONCENTER_ON            XSTR("GrowlNotificationCenterOn!")
346
347/*!     @defined GROWL_DISTRIBUTED_NOTIFICATION_NOTIFICATIONCENTER_OFF
348 *      @abstract The distributed notification sent when the Notification Center support is toggled off in Growl 2.0
349 *      @discussion When the user enables Notification Center support in Growl 2.0, this notification is sent
350 *      to inform all running apps that they should no longer speak to Notification Center directly.
351 */
352#define GROWL_DISTRIBUTED_NOTIFICATION_NOTIFICATIONCENTER_OFF           XSTR("GrowlNotificationCenterOff!")
353
354/*!     @defined GROWL_DISTRIBUTED_NOTIFICATION_NOTIFICATIONCENTER_QUERY
355 *      @abstract The distributed notification sent by an application to query Growl 2.0's notification center support.
356 *      @discussion When an app starts up, it will send this query to get Growl 2.0 to spit out whether notification
357 *      center support is on or off.
358 */
359#define GROWL_DISTRIBUTED_NOTIFICATION_NOTIFICATIONCENTER_QUERY         XSTR("GrowlNotificationCenterYN?")
360
361
362/*!     @group Other symbols */
363/* Symbols which don't fit into any of the other categories. */
364
365/*!     @defined GROWL_KEY_CLICKED_CONTEXT
366 *      @abstract Used internally as the key for the clickedContext passed over DNC.
367 *      @discussion This key is used in GROWL_NOTIFICATION_CLICKED, and contains the
368 *       click context that was supplied in the original notification.
369 */
370#define GROWL_KEY_CLICKED_CONTEXT               XSTR("ClickedContext")
371/*!     @defined GROWL_REG_DICT_EXTENSION
372 *      @abstract The filename extension for registration dictionaries.
373 *      @discussion The GrowlApplicationBridge in Growl.framework registers with
374 *       Growl by creating a file with the extension of .(GROWL_REG_DICT_EXTENSION)
375 *       and opening it in the GrowlHelperApp. This happens whether or not Growl is
376 *       running; if it was stopped, it quits immediately without listening for
377 *       notifications.
378 */
379#define GROWL_REG_DICT_EXTENSION                XSTR("growlRegDict")
380
381
382#define GROWL_POSITION_PREFERENCE_KEY                   @"GrowlSelectedPosition"
383
384#define GROWL_PLUGIN_CONFIG_ID XSTR("GrowlPluginConfigurationID")
385
386#endif //ndef _GROWLDEFINES_H
Note: See TracBrowser for help on using the repository browser.