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)