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.

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