Structs



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

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