Growl_Delegate |
Delegate to supply GrowlApplicationBridge with information and respond to events.
struct Growl_Delegate { /* @discussion This should be sizeof(struct Growl_Delegate). */ size_t size; /*All of these attributes are optional. *Optional attributes can be NULL; required attributes that * are NULL cause setting the Growl delegate to fail. *XXX - move optional/required status into the discussion for each field */ /* This name is used both internally and in the Growl preferences. * * This should remain stable between different versions and incarnations of * your application. * For example, "SurfWriter" is a good app name, whereas "SurfWriter 2.0" and * "SurfWriter Lite" are not. * * This can be <code>NULL</code> if it is provided elsewhere, namely in an * auto-discoverable plist file in your app bundle * (XXX refer to more information on that) or in registrationDictionary. */ CFStringRef applicationName; /* * Must contain at least these keys: * GROWL_NOTIFICATIONS_ALL (CFArray): * Contains the names of all notifications your application may post. * * Can also contain these keys: * GROWL_NOTIFICATIONS_DEFAULT (CFArray): * Names of notifications that should be enabled by default. * If omitted, GROWL_NOTIFICATIONS_ALL will be used. * GROWL_APP_NAME (CFString): * Same as the applicationName member of this structure. * If both are present, the applicationName member shall prevail. * If this key is present, you may omit applicationName (set it to <code>NULL</code>). * GROWL_APP_ICON (CFData): * Same as the iconData member of this structure. * If both are present, the iconData member shall prevail. * If this key is present, you may omit iconData (set it to <code>NULL</code>). * * If you change the contents of this dictionary after setting the delegate, * be sure to call Growl_Reregister. * * This can be <code>NULL</code> if you have an auto-discoverable plist file in your app * bundle. (XXX refer to more information on that) */ CFDictionaryRef registrationDictionary; /* The data can be in any format supported by NSImage. As of * Mac OS X 10.3, this includes the .icns, TIFF, JPEG, GIF, PNG, PDF, and * PICT formats. * * If this is not supplied, Growl will look up your application's icon by * its application name. */ CFDataRef applicationIconData; /* Installer display attributes * * These four attributes are used by the Growl installer, if this framework * supports it. * For any of these being <code>NULL</code>, a localised default will be * supplied. */ /* If this is <code>NULL</code>, Growl will use a default, * localized title. * * Only used if you're using Growl-WithInstaller.framework. Otherwise, * this member is ignored. */ CFStringRef growlInstallationWindowTitle; /* This information may be as long or short as desired (the * window will be sized to fit it). If Growl is not installed, it will * be displayed to the user as an explanation of what Growl is and what * it can do in your application. * It should probably note that no download is required to install. * * If this is <code>NULL</code>, Growl will use a default, localized * explanation. * * Only used if you're using Growl-WithInstaller.framework. Otherwise, * this member is ignored. */ CFStringRef growlInstallationInformation; /* If this is <code>NULL</code>, Growl will use a default, * localized title. * * Only used if you're using Growl-WithInstaller.framework. Otherwise, * this member is ignored. */ CFStringRef growlUpdateWindowTitle; /* This information may be as long or short as desired (the * window will be sized to fit it). If an older version of Growl is * installed, it will be displayed to the user as an explanation that an * updated version of Growl is included in your application and * no download is required. * * If this is <code>NULL</code>, Growl will use a default, localized * explanation. * * Only used if you're using Growl-WithInstaller.framework. Otherwise, * this member is ignored. */ CFStringRef growlUpdateInformation; /* This member is provided for use by your retain and release * callbacks (see below). * * GrowlApplicationBridge never directly uses this member. Instead, it * calls your retain callback (if non-<code>NULL</code>) and your release * callback (if non-<code>NULL</code>). */ unsigned referenceCount; //Functions. Currently all of these are optional (any of them can be NULL). /* When you call Growl_SetDelegate(newDelegate), it will call * oldDelegate->release(oldDelegate), and then it will call * newDelegate->retain(newDelegate), and the return value from retain * is what will be set as the delegate. NSObject retain] * This member is optional (it can be <code>NULL</code>). * For a delegate allocated with malloc, this member would be * <code>NULL</code>. * @result A delegate to which GrowlApplicationBridge holds a reference. */ void *(*retain)( void *); /* When you call Growl_SetDelegate(newDelegate), it will call * oldDelegate->release(oldDelegate), and then it will call * newDelegate->retain(newDelegate), and the return value from retain * is what will be set as the delegate. * (This means that this member works like CFRelease and NSObject release] * This member is optional (it can be NULL). * For a delegate allocated with malloc, this member might be * <code>free</code>(3). */ void (*release)( void *); /* Informs the delegate that Growl (specifically, the GrowlHelperApp) was * launched successfully (or was already running). The application can * take actions with the knowledge that Growl is installed and functional. */ void (*growlIsReady)( void); /* Informs the delegate that a Growl notification was clicked. It is only * sent for notifications sent with a non-<code>NULL</code> clickContext, * so if you want to receive a message when a notification is clicked, * clickContext must not be <code>NULL</code> when calling * Growl_PostNotification or * Growl_NotifyWithTitleDescriptionNameIconPriorityStickyClickContext. */ void (*growlNotificationWasClicked)( CFPropertyListRef clickContext); /* Informs the delegate that a Growl notification timed out. It is only * sent for notifications sent with a non-<code>NULL</code> clickContext, * so if you want to receive a message when a notification is clicked, * clickContext must not be <code>NULL</code> when calling * Growl_PostNotification or * Growl_NotifyWithTitleDescriptionNameIconPriorityStickyClickContext. */ void (*growlNotificationTimedOut)( CFPropertyListRef clickContext); };
size
- The size of the delegate structure.
applicationName
- The name of your application.
registrationDictionary
- A dictionary describing your application and the notifications it can send out.
applicationIconData
- Your application's icon.
growlInstallationWindowTitle
- The title of the installation window.
growlInstallationInformation
- Text to display in the installation window.
growlUpdateWindowTitle
- The title of the update window.
growlUpdateInformation
- Text to display in the update window.
referenceCount
- A count of owners of the delegate.
retain
- Called when GrowlApplicationBridge receives this delegate.
release
- Called when GrowlApplicationBridge no longer needs this delegate.
growlIsReady
- Called when GrowlHelperApp is listening for notifications.
growlNotificationWasClicked
- Called when a Growl notification is clicked.
growlNotificationTimedOut
- Called when a Growl notification timed out.
The Growl delegate provides your interface to
GrowlApplicationBridge. When GrowlApplicationBridge needs information about
your application, it looks for it in the delegate; when Growl or the user
does something that you might be interested in, GrowlApplicationBridge
looks for a callback in the delegate and calls it if present
(meaning, if it is not NULL
).
XXX on all of that
Growl_Notification |
Structure describing a Growl notification.
struct Growl_Notification { /* This should be sizeof(struct Growl_Notification). */ size_t size; /* The notification name distinguishes one type of * notification from another. The name should be human-readable, as it * will be displayed in the Growl preference pane. * * The name is used in the GROWL_NOTIFICATIONS_ALL and * GROWL_NOTIFICATIONS_DEFAULT arrays in the registration dictionary, and * in this member of the Growl_Notification structure. */ CFStringRef name; /* A notification's title describes the notification briefly. * It should be easy to read quickly by the user. */ CFStringRef title; /* The description supplements the title with more * information. It is usually longer and sometimes involves a list of * subjects. For example, for a 'Download complete' notification, the * description might have one filename per line. GrowlMail in Growl 0.6 * uses a description of '%d new mail(s)' (formatted with the number of * messages). */ CFStringRef description; /* The notification icon usually indicates either what * happened (it may have the same icon as e.g. a toolbar item that * started the process that led to the notification), or what it happened * to (e.g. a document icon). * * The icon data is optional, so it can be <code>NULL</code>. In that * case, the application icon is used alone. Not all displays support * icons. * * The data can be in any format supported by NSImage. As of Mac OS X * 10.3, this includes the .icns, TIFF, JPEG, GIF, PNG, PDF, and PICT form * ats. */ CFDataRef iconData; /* Priority is new in Growl 0.6, and is represented as a * signed integer from -2 to +2. 0 is Normal priority, -2 is Very Low * priority, and +2 is Very High priority. * * Not all displays support priority. If you do not wish to assign a * priority to your notification, assign 0. */ signed int priority; /* These bits are not used in Growl 0.6. Set them to 0. */ unsigned reserved: 31; /* When the sticky bit is clear, in most displays, * notifications disappear after a certain amount of time. Sticky * notifications, however, remain on-screen until the user dismisses them * explicitly, usually by clicking them. * * Sticky notifications were introduced in Growl 0.6. Most notifications * should not be sticky. Not all displays support sticky notifications, * and the user may choose in Growl's preference pane to force the * notification to be sticky or non-sticky, in which case the sticky bit * in the notification will be ignored. */ unsigned isSticky: 1; /* If this is not <code>NULL</code>, and your click callback * is not <code>NULL</code> either, this will be passed to the callback * when your notification is clicked by the user. * * Click feedback was introduced in Growl 0.6, and it is optional. Not * all displays support click feedback. */ CFPropertyListRef clickContext; /* If this is not <code>NULL</code>, it will be called instead * of the Growl delegate's click callback when clickContext is * non-<code>NULL</code> and the notification is clicked on by the user. * * Click feedback was introduced in Growl 0.6, and it is optional. Not * all displays support click feedback. * * The per-notification click callback is not yet supported as of Growl * 0.7. */ void (*clickCallback)( CFPropertyListRef clickContext); };
size
- The size of the notification structure.
name
- Identifies the notification.
title
- Short synopsis of the notification.
description
- Additional text.
iconData
- An icon for the notification.
priority
- An indicator of the notification's importance.
reserved
- Bits reserved for future usage.
isSticky
- Requests that a notification stay on-screen until dismissed explicitly.
clickContext
- An identifier to be passed to your click callback when a notification is clicked.
clickCallback
- A callback to call when the notification is clicked.
XXX
© The Growl Project (Last Updated May 14, 2005)