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

Last change on this file since 8838 was 8838, checked in by livings124, 13 years ago

add experimental Growl snapshot

File size: 15.4 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#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
Note: See TracBrowser for help on using the repository browser.