GrowlApplicationBridge-Carbon.h


Abstract

Declares an API that Carbon applications can use to interact with Growl.

Discussion

GrowlApplicationBridge uses a delegate to provide information //XXX to Growl (such as your application's name and what notifications it may post) and to provide information to your application (such as that Growl is listening for notifications or that a notification has been clicked).

You can set the Growldelegate with Growl_SetDelegate and find out the current delegate with Growl_GetDelegate. See struct Growl_Delegate for more information about the delegate.



Functions

Growl_CopyRegistrationDictionaryFromBundle
Looks in a bundle for a registration dictionary.
Growl_CopyRegistrationDictionaryFromDelegate
Asks the delegate for a registration dictionary.
Growl_CreateBestRegistrationDictionary
Obtains a registration dictionary, filled out to the best of GrowlApplicationBridge's knowledge.
Growl_CreateRegistrationDictionaryByFillingInDictionary
Tries to fill in missing keys in a registration dictionary.
Growl_CreateRegistrationDictionaryByFillingInDictionaryRestrictedToKeys
Tries to fill in missing keys in a registration dictionary.
Growl_GetDelegate
Returns the current Growl delegate, if any.
Growl_IsInstalled
Determines whether the Growl prefpane and its helper app are installed.
Growl_IsRunning
Cycles through the process list to find whether GrowlHelperApp is running.
Growl_LaunchIfInstalled
Launches GrowlHelperApp if it is not already running.
Growl_NotifyWithTitleDescriptionNameIconPriorityStickyClickContext
Posts a Growl notification using parameter values.
Growl_PostNotification
Posts a Growl notification.
Growl_PostNotificationWithDictionary
Notifies using a userInfo dictionary suitable for passing to CFDistributedNotificationCenter.
Growl_RegisterWithDictionary
Register your application with Growl without setting a delegate.
Growl_Reregister
Updates your registration with Growl.
Growl_SetDelegate
Replaces the current Growl delegate with a new one, or removes the Growl delegate.
Growl_SetWillRegisterWhenGrowlIsReady
Tells GrowlApplicationBridge to register with Growl when Growl launches (or not).
Growl_WillRegisterWhenGrowlIsReady
Reports whether GrowlApplicationBridge will register with Growl when Growl next launches.

Growl_CopyRegistrationDictionaryFromBundle


Looks in a bundle for a registration dictionary.

CFDictionaryRef Growl_CopyRegistrationDictionaryFromBundle(
    CFBundleRef bundle); 
function result
A registration dictionary.
Discussion

This function looks in a bundle for an auto-discoverable registration dictionary file using CFBundleCopyResourceURL. If it finds one, it loads the file using CFPropertyList and returns the result.

If you pass NULL as the bundle, the main bundle is examined.

This function does not attempt to clean up the dictionary in any way - for example, if it is missing the GROWL_APP_NAME key, the result will be missing it too. Use Growl_CreateRegistrationDictionaryByFillingInDictionary: or Growl_CreateRegistrationDictionaryByFillingInDictionaryRestrictedToKeys to try to fill in missing keys.

This function was introduced in Growl.framework 0.7.


Growl_CopyRegistrationDictionaryFromDelegate


Asks the delegate for a registration dictionary.

CFDictionaryRef Growl_CopyRegistrationDictionaryFromDelegate(
    void); 
function result
A registration dictionary.
Discussion

If no delegate is set, or if the delegate's registrationDictionary member is NULL, this function returns NULL.

This function does not attempt to clean up the dictionary in any way - for example, if it is missing the GROWL_APP_NAME key, the result will be missing it too. Use Growl_CreateRegistrationDictionaryByFillingInDictionary: or Growl_CreateRegistrationDictionaryByFillingInDictionaryRestrictedToKeys to try to fill in missing keys.

This function was introduced in Growl.framework 0.7.


Growl_CreateBestRegistrationDictionary


Obtains a registration dictionary, filled out to the best of GrowlApplicationBridge's knowledge.

CFDictionaryRef Growl_CreateBestRegistrationDictionary(
    void); 
function result
A registration dictionary.
Discussion

This function creates a registration dictionary as best GrowlApplicationBridge knows how.

First, GrowlApplicationBridge examines the Growl delegate (if there is one) and gets the registration dictionary from that. If no such dictionary was obtained, GrowlApplicationBridge looks in your application's main bundle for an auto-discoverable registration dictionary file. If that doesn't exist either, this function returns NULL.

Second, GrowlApplicationBridge calls Growl_CreateRegistrationDictionaryByFillingInDictionary with whatever dictionary was obtained. The result of that function is the result of this function.

GrowlApplicationBridge uses this function when you call Growl_SetDelegate, or when you call Growl_RegisterWithDictionary with NULL.

This function was introduced in Growl.framework 0.7.


Growl_CreateRegistrationDictionaryByFillingInDictionary


Tries to fill in missing keys in a registration dictionary.

CFDictionaryRef Growl_CreateRegistrationDictionaryByFillingInDictionary(
    CFDictionaryRef regDict); 
Parameter Descriptions
regDict
The dictionary to fill in.
function result
The dictionary with the keys filled in.
Discussion

This function examines the passed-in dictionary for missing keys, and tries to work out correct values for them. As of 0.7, it uses:

Key Value --- ----- GROWL_APP_NAME CFBundleExecutableName GROWL_APP_ICON The icon of the application. GROWL_APP_LOCATION The location of the application. GROWL_NOTIFICATIONS_DEFAULT GROWL_NOTIFICATIONS_ALL

Keys are only filled in if missing; if a key is present in the dictionary, its value will not be changed.

This function was introduced in Growl.framework 0.7.


Growl_CreateRegistrationDictionaryByFillingInDictionaryRestrictedToKeys


Tries to fill in missing keys in a registration dictionary.

CFDictionaryRef Growl_CreateRegistrationDictionaryByFillingInDictionaryRestrictedToKeys(
    CFDictionaryRef regDict,
    CFSetRef keys); 
Parameter Descriptions
regDict
The dictionary to fill in.
keys
The keys to fill in. If NULL, any missing keys are filled in.
function result
The dictionary with the keys filled in.
Discussion

This function examines the passed-in dictionary for missing keys, and tries to work out correct values for them. As of 0.7, it uses:

Key Value --- ----- GROWL_APP_NAME CFBundleExecutableName GROWL_APP_ICON The icon of the application. GROWL_APP_LOCATION The location of the application. GROWL_NOTIFICATIONS_DEFAULT GROWL_NOTIFICATIONS_ALL

Only those keys that are listed in keys will be filled in. Other missing keys are ignored. Also, keys are only filled in if missing; if a key is present in the dictionary, its value will not be changed.

This function was introduced in Growl.framework 0.7.


Growl_GetDelegate


Returns the current Growl delegate, if any.

struct Growl_Delegate *Growl_GetDelegate(
    void); 
function result
The current Growl delegate.
Discussion

Returns the last pointer passed into Growl_SetDelegate, or NULL if no such call has been made.

This function follows standard Core Foundation reference-counting rules. Because it is a Get function, not a Copy function, it will not retain the delegate on your behalf. You are responsible for retaining and releasing the delegate as needed.


Growl_IsInstalled


Determines whether the Growl prefpane and its helper app are installed.

Boolean Growl_IsInstalled(
    void); 
function result
Returns true if Growl is installed, false otherwise.

Growl_IsRunning


Cycles through the process list to find whether GrowlHelperApp is running.

Boolean Growl_IsRunning(
    void); 
function result
Returns true if Growl is running, false otherwise.

Growl_LaunchIfInstalled


Launches GrowlHelperApp if it is not already running.

Boolean Growl_LaunchIfInstalled(
    GrowlLaunchCallback callback,
    void *context); 
Parameter Descriptions
callback
A callback function which will be called if Growl was successfully launched or was already running. Can be NULL.
context
The context pointer to pass to the callback. Can be NULL.
function result
Returns true if Growl was successfully launched or was already running; returns false and does not call the callback otherwise.
Discussion

Returns true and calls the callback (if the callback is not NULL) if the Growl helper app began launching or was already running. Returns false and performs no other action if Growl could not be launched (e.g. because the Growl preference pane is not properly installed).

If Growl_CreateBestRegistrationDictionary returns non-NULL, this function will register with Growl atomically.

The callback should take a single argument; this is to allow applications to have context-relevant information passed back. It is perfectly acceptable for context to be NULL. The callback itself can be NULL if you don't want one.


Growl_NotifyWithTitleDescriptionNameIconPriorityStickyClickContext


Posts a Growl notification using parameter values.

void Growl_NotifyWithTitleDescriptionNameIconPriorityStickyClickContext( 
    /*inhale*/
    CFStringRef title, 
    CFStringRef description, 
    CFStringRef notificationName, 
    CFDataRef iconData, 
    signed int priority, 
    Boolean isSticky, 
    CFPropertyListRef clickContext); 
Parameter Descriptions
title
The title of the notification.
description
The description of the notification.
notificationName
The name of the notification as listed in the registration dictionary.
iconData
Data representing a notification icon. Can be NULL.
priority
The priority of the notification (-2 to +2, with -2 being Very Low and +2 being Very High).
isSticky
If true, requests that this notification wait for a response from the user.
clickContext
An object to pass to the clickCallback, if any. Can be NULL, in which case the clickCallback is not called.
Discussion

Creates a temporary Growl_Notification, fills it out with the supplied information, and calls Growl_PostNotification on it. See struct Growl_Notification and Growl_PostNotification for more information.

The icon data can be in any format supported by NSImage. As of Mac OS X


Growl_PostNotification


Posts a Growl notification.

void Growl_PostNotification(
    const struct Growl_Notification *notification); 
Parameter Descriptions
notification
The notification to post.
Discussion

This is the preferred means for sending a Growl notification. The notification name and at least one of the title and description are required (all three are preferred). All other parameters may be NULL (or 0 or false as appropriate) to accept default values.

If using the Growl-WithInstaller framework, if Growl is not installed the user will be prompted to install Growl. If the user cancels, this function will have no effect until the next application session, at which time when it is called the user will be prompted again. The user is also given the option to not be prompted again. If the user does choose to install Growl, the requested notification will be displayed once Growl is installed and running.


Growl_PostNotificationWithDictionary


Notifies using a userInfo dictionary suitable for passing to CFDistributedNotificationCenter.

void Growl_PostNotificationWithDictionary(
    CFDictionaryRef userInfo); 
Parameter Descriptions
userInfo
The dictionary to notify with.
Discussion

Before Growl 0.6, your application would have posted notifications using CFDistributedNotificationCenter by creating a userInfo dictionary with the notification data. This had the advantage of allowing you to add other data to the dictionary for programs besides Growl that might be listening.

This function allows you to use such dictionaries without being restricted to using CFDistributedNotificationCenter. The keys for this dictionary can be found in GrowlDefines.h.


Growl_RegisterWithDictionary


Register your application with Growl without setting a delegate.

Boolean Growl_RegisterWithDictionary(
    CFDictionaryRef regDict); 
function result
false if registration failed (e.g. if Growl isn't installed).
Discussion

When you call this function with a dictionary, GrowlApplicationBridge registers your application using that dictionary. If you pass NULL, GrowlApplicationBridge will ask the delegate (if there is one) for a dictionary, and if that doesn't work, it will look in your application's bundle for an auto-discoverable plist. (XXX refer to more information on that)

If you pass a dictionary to this function, it must include the GROWL_APP_NAME key, unless a delegate is set.

This function is mainly an alternative to the delegate system introduced with Growl 0.6. Without a delegate, you cannot receive callbacks such as growlIsReady (since they are sent to the delegate). You can, however, set a delegate after registering without one.

This function was introduced in Growl.framework 0.7.


Growl_Reregister


Updates your registration with Growl.

void Growl_Reregister(
    void); 
Discussion

If your application changes the contents of the GROWL_NOTIFICATIONS_ALL key in the registrationDictionary member of the Growl delegate, or if it changes the value of that member, or if it changes the contents of its auto-discoverable plist, call this function to have Growl update its registration information for your application.

Otherwise, this function does not normally need to be called. If you're using a delegate, your application will be registered when you set the delegate if both the delegate and its registrationDictionary member are non-NULL.

This function is now implemented using Growl_RegisterWithDictionary.


Growl_SetDelegate


Replaces the current Growl delegate with a new one, or removes the Growl delegate.

Boolean Growl_SetDelegate(
    struct Growl_Delegate *newDelegate); 
Parameter Descriptions
newDelegate
function result
Returns false and does nothing else if a pointer that was passed in is unsatisfactory (because it is non-NULL, but at least one required member of it is NULL). Otherwise, sets or unsets the delegate and returns true.
Discussion

When newDelegate is non-NULL, sets the delegate to newDelegate. When it is NULL, the current delegate will be unset, and no delegate will be in place.

It is legal for newDelegate to be the current delegate; nothing will happen, and Growl_SetDelegate will return true. It is also legal for it to be NULL, as described above; again, it will return true.

If there was a delegate in place before the call, Growl_SetDelegate will call the old delegate's release member if it was non-NULL. If newDelegate is non-NULL, Growl_SetDelegate will call newDelegate->retain, and set the delegate to its return value.

If you are using Growl-WithInstaller.framework, and an older version of Growl is installed on the user's system, the user will automatically be prompted to update.

GrowlApplicationBridge currently does not copy this structure, nor does it retain any of the CF objects in the structure (it regards the structure as a container that retains the objects when they are added and releases them when they are removed or the structure is destroyed). Also, GrowlApplicationBridge currently does not modify any member of the structure, except possibly the referenceCount by calling the retain and release members.


Growl_SetWillRegisterWhenGrowlIsReady


Tells GrowlApplicationBridge to register with Growl when Growl launches (or not).

void Growl_SetWillRegisterWhenGrowlIsReady(
    Boolean flag); 
Parameter Descriptions
flag
true if you want GrowlApplicationBridge to register with Growl when next it is ready; false if not.
Discussion

When Growl has started listening for notifications, it posts a GROWL_IS_READY notification on the Distributed Notification Center. GrowlApplicationBridge listens for this notification, using it to perform various tasks (such as calling your delegate's growlIsReady callback, if it has one). If this function is called with true, one of those tasks will be to reregister with Growl (in the manner of Growl_Reregister).

This attribute is automatically set back to false (the default) after every GROWL_IS_READY notification.


Growl_WillRegisterWhenGrowlIsReady


Reports whether GrowlApplicationBridge will register with Growl when Growl next launches.

Boolean Growl_WillRegisterWhenGrowlIsReady(
    void); 
function result
true if GrowlApplicationBridge will register with Growl when next it posts GROWL_IS_READY; false if not.

Typedefs


GrowlLaunchCallback


Callback to notify you that Growl is running.

typedef void (*GrowlLaunchCallback)(
    void *context); 
Parameter Descriptions
context
The context pointer passed to Growl_LaunchIfInstalled.
Discussion

Growl_LaunchIfInstalled calls this callback function if Growl was already running or if it launched Growl successfully.

Structs and Unions


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); 
}; 
Field Descriptions
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.
Discussion

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); 
}; 
Field Descriptions
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.
Discussion

XXX

#defines


GROWL_PREFPANE_BUNDLE_IDENTIFIER


The CFBundleIdentifier of the Growl preference pane bundle.

#define GROWL_PREFPANE_BUNDLE_IDENTIFIER CFSTR(
    "com.growl.prefpanel") 
Discussion

GrowlApplicationBridge uses this to determine whether Growl is currently installed, by searching for the Growl preference pane. Your application probably does not need to use this macro itself.


InitGrowlDelegate


Callable macro. Initializes a Growl delegate structure to defaults.

#define InitGrowlDelegate(
    delegate) \ do {
    \ if (
    delegate) {
    \ (
    delegate)->size = sizeof(
    struct Growl_Delegate); \ (
    delegate)->applicationName = NULL; \ (
    delegate)->registrationDictionary = NULL; \ (
    delegate)->applicationIconData = NULL; \ (
    delegate)->growlInstallationWindowTitle = NULL; \ (
    delegate)->growlInstallationInformation = NULL; \ (
    delegate)->growlUpdateWindowTitle = NULL; \ (
    delegate)->growlUpdateInformation = NULL; \ (
    delegate)->referenceCount = 1U; \ (
    delegate)->retain = NULL; \ (
    delegate)->release = NULL; \ (
    delegate)->growlIsReady = NULL; \ (
    delegate)->growlNotificationWasClicked = NULL; \ (
    delegate)->growlNotificationTimedOut = NULL; \ 
} \ 
} while(
    0) 
Discussion

Call with a pointer to a struct Growl_Delegate. All of the members of the structure will be set to 0 or NULL, except for size (which will be set to sizeof(struct Growl_Delegate)) and referenceCount (which will be set to 1).


InitGrowlNotification


Callable macro. Initializes a Growl notification structure to defaults.

#define InitGrowlNotification(
    notification) \ do {
    \ if (
    notification) {
    \ (
    notification)->size = sizeof(
    struct Growl_Notification); \ (
    notification)->name = NULL; \ (
    notification)->title = NULL; \ (
    notification)->description = NULL; \ (
    notification)->iconData = NULL; \ (
    notification)->priority = 0; \ (
    notification)->reserved = 0U; \ (
    notification)->isSticky = false; \ (
    notification)->clickContext = NULL; \ 
} \ 
} while(
    0) 
Discussion

Call with a pointer to a struct Growl_Notification. All of the members of the structure will be set to 0 or NULL, except for size (which will be set to sizeof(struct Growl_Notification)).

© The Growl Project (Last Updated May 14, 2005)