Growl_CopyRegistrationDictionaryFromBundle |
Looks in a bundle for a registration dictionary.
CFDictionaryRef Growl_CopyRegistrationDictionaryFromBundle( CFBundleRef bundle);
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);
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);
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);
regDict
- The dictionary to fill in.
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);
regDict
- The dictionary to fill in.
keys
- The keys to fill in. If
NULL
, any missing keys are filled in.
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);
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);
Growl_IsRunning |
Cycles through the process list to find whether GrowlHelperApp is running.
Boolean Growl_IsRunning( void);
Growl_LaunchIfInstalled |
Launches GrowlHelperApp if it is not already running.
Boolean Growl_LaunchIfInstalled( GrowlLaunchCallback callback, void *context);
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
.
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);
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.
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);
notification
- The notification to post.
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);
userInfo
- The dictionary to notify with.
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);
false
if registration failed (e.g. if Growl isn't installed).
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);
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);
newDelegate
NULL
, but at least one
required member of it is NULL
). Otherwise, sets or unsets the
delegate and returns true.
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);
flag
true
if you want GrowlApplicationBridge to register with Growl when next it is ready;false
if not.
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);
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)