GrowlApplicationBridge


Abstract

A class used to interface with Growl.

Discussion

This class provides a means to interface with Growl.

Currently it provides a way to detect if Growl is installed and launch the GrowlHelperApp if it's not already running.



Methods

+bestRegistrationDictionary
Obtains a registration dictionary, filled out to the best of GrowlApplicationBridge's knowledge.
+growlDelegate
Return the object responsible for providing and receiving Growl information.
+isGrowlInstalled
Detects whether Growl is installed.
+isGrowlRunning
Detects whether GrowlHelperApp is currently running.
+notifyWithDictionary:
Notifies using a userInfo dictionary suitable for passing to NSDistributedNotificationCenter.
+notifyWithTitle:description:notificationName:iconData:priority:isSticky:clickContext:
Send a Growl notification.
+registerWithDictionary:
Register your application with Growl without setting a delegate.
+registrationDictionaryByFillingInDictionary:
Tries to fill in missing keys in a registration dictionary.
+registrationDictionaryByFillingInDictionary:restrictToKeys:
Tries to fill in missing keys in a registration dictionary.
+registrationDictionaryFromBundle:
Looks in a bundle for a registration dictionary.
+registrationDictionaryFromDelegate
Asks the delegate for a registration dictionary.
+reregisterGrowlNotifications
Reregister the notifications for this application.
+setGrowlDelegate:
Set the object which will be responsible for providing and receiving Growl information.
+setWillRegisterWhenGrowlIsReady:
Tells GrowlApplicationBridge to register with Growl when Growl launches (or not).
+willRegisterWhenGrowlIsReady
Reports whether GrowlApplicationBridge will register with Growl when Growl next launches.

bestRegistrationDictionary


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

+ (NSDictionary *) bestRegistrationDictionary;
method result
A registration dictionary.
Discussion

This method creates a registration dictionary as best GrowlApplicationBridge knows how.
First, GrowlApplicationBridge contacts 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 method returns nil.
Second, GrowlApplicationBridge calls +registrationDictionaryByFillingInDictionary: with whatever dictionary was obtained. The result of that method is the result of this method.
GrowlApplicationBridge uses this method when you call +setGrowlDelegate:, or when you call +registerWithDictionary: with nil.
This method was introduced in Growl.framework 0.7.


growlDelegate


Return the object responsible for providing and receiving Growl information.

+ (NSObject<GrowlApplicationBridgeDelegate> *) growlDelegate;
method result
The Growl delegate.
Discussion

See setGrowlDelegate: for details.


isGrowlInstalled


Detects whether Growl is installed.

+ (BOOL) isGrowlInstalled;
method result
Returns YES if Growl is installed, NO otherwise.
Discussion

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


isGrowlRunning


Detects whether GrowlHelperApp is currently running.

+ (BOOL) isGrowlRunning;
method result
Returns YES if GrowlHelperApp is running, NO otherwise.
Discussion

Cycles through the process list to find whether GrowlHelperApp is running and returns its findings.


notifyWithDictionary:


Notifies using a userInfo dictionary suitable for passing to NSDistributedNotificationCenter.

+ (void) notifyWithDictionary:(NSDictionary *)userInfo;
Parameter Descriptions
userInfo
The dictionary to notify with.
Discussion

Before Growl 0.6, your application would have posted notifications using NSDistributedNotificationCenter 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 method allows you to use such dictionaries without being restricted to using NSDistributedNotificationCenter. The keys for this dictionary can be found in GrowlDefines.h.


notifyWithTitle:description:notificationName:iconData:priority:isSticky:clickContext:


Send a Growl notification.

+ (void) notifyWithTitle:(NSString *)title description:(NSString *)description notificationName:(NSString *)notifName iconData:(NSData *)iconData priority:(signed int)priority isSticky:(BOOL)isSticky clickContext:(id)clickContext;
Parameter Descriptions
title
The title of the notification displayed to the user.
description
The full description of the notification displayed to the user.
notifName
The internal name of the notification. Should be human-readable, as it will be displayed in the Growl preference pane.
iconData
NSData object to show with the notification as its icon. If nil, the application's icon will be used instead.
priority
The priority of the notification. The default value is 0; positive values are higher priority and negative values are lower priority. Not all Growl displays support priority.
isSticky
If YES, the notification will remain on screen until clicked. Not all Growl displays support sticky notifications.
clickContext
A context passed back to the Growl delegate if it implements -(void)growlNotificationWasClicked: and the notification is clicked. Not all display plugins support clicking. The clickContext must be plist-encodable (completely of NSString, NSArray, NSNumber, NSDictionary, and NSData types).
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 nil (or 0 or NO 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 method 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.


registerWithDictionary:


Register your application with Growl without setting a delegate.

+ (BOOL) registerWithDictionary:(NSDictionary *)regDict;
Discussion

When you call this method with a dictionary, GrowlApplicationBridge registers your application using that dictionary. If you pass nil, 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 method, it must include the GROWL_APP_NAME key, unless a delegate is set.
This method 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 method was introduced in Growl.framework 0.7.


registrationDictionaryByFillingInDictionary:


Tries to fill in missing keys in a registration dictionary.

+ (NSDictionary *) 
        registrationDictionaryByFillingInDictionary:(NSDictionary *)regDict;
Parameter Descriptions
regDict
The dictionary to fill in.
method result
The dictionary with the keys filled in. This is an autoreleased copy of regDict.
Discussion

This method 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 method was introduced in Growl.framework 0.7.


registrationDictionaryByFillingInDictionary:restrictToKeys:


Tries to fill in missing keys in a registration dictionary.

+ (NSDictionary *) 
        registrationDictionaryByFillingInDictionary:(NSDictionary *)regDict 
        restrictToKeys:(NSSet *)keys;
Parameter Descriptions
regDict
The dictionary to fill in.
keys
The keys to fill in. If nil, any missing keys are filled in.
method result
The dictionary with the keys filled in. This is an autoreleased copy of regDict.
Discussion

This method 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 method was introduced in Growl.framework 0.7.


registrationDictionaryFromBundle:


Looks in a bundle for a registration dictionary.

+ (NSDictionary *) registrationDictionaryFromBundle:(NSBundle *)bundle;
method result
A registration dictionary.
Discussion

This method looks in a bundle for an auto-discoverable registration dictionary file using -[. If it finds one, it loads the file usingNSBundle pathForResource:ofType:] +[ and returns theNSDictionary dictionaryWithContentsOfFile:] result.
If you pass nil as the bundle, the main bundle is examined.
This method 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 +[ orGrowlApplicationBridge registrationDictionaryByFillingInDictionary:] +[ to tryGrowlApplicationBridge registrationDictionaryByFillingInDictionary:restrictToKeys:] to fill in missing keys.
This method was introduced in Growl.framework 0.7.


registrationDictionaryFromDelegate


Asks the delegate for a registration dictionary.

+ (NSDictionary *) registrationDictionaryFromDelegate;
method result
A registration dictionary.
Discussion

If no delegate is set, or if the delegate's -registrationDictionaryForGrowl method returns nil, this method returns nil.
This method 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 +[ orGrowlApplicationBridge registrationDictionaryByFillingInDictionary:] +[ to tryGrowlApplicationBridge registrationDictionaryByFillingInDictionary:restrictToKeys:] to fill in missing keys.
This method was introduced in Growl.framework 0.7.


reregisterGrowlNotifications


Reregister the notifications for this application.

+ (void) reregisterGrowlNotifications;
Discussion

This method does not normally need to be called. If your application changes what notifications it is registering with Growl, call this method to have the Growl delegate's -registrationDictionaryForGrowl method called again and the Growl registration information updated.
This method is now implemented using -registerWithDictionary:.


setGrowlDelegate:


Set the object which will be responsible for providing and receiving Growl information.

+ (void) setGrowlDelegate:(NSObject<GrowlApplicationBridgeDelegate> *)inDelegate;
Parameter Descriptions
inDelegate
The delegate for the GrowlApplicationBridge. It must conform to the GrowlApplicationBridgeDelegate protocol.
Discussion

This must be called before using GrowlApplicationBridge.
The methods in the GrowlApplicationBridgeDelegate protocol are required and return the basic information needed to register with Growl.
The methods in the GrowlApplicationBridgeDelegate_InformalProtocol informal protocol are individually optional. They provide a greater degree of interaction between the application and growl such as informing the application when one of its Growl notifications is clicked by the user.
The methods in the GrowlApplicationBridgeDelegate_Installation_InformalProtocol informal protocol are individually optional and are only applicable when using the Growl-WithInstaller.framework which allows for automated Growl installation.
When this method is called, data will be collected from inDelegate, Growl will be launched if it is not already running, and the application will be registered with Growl.
If using the Growl-WithInstaller framework, if Growl is already installed but this copy of the framework has an updated version of Growl, the user will be prompted to update automatically.


setWillRegisterWhenGrowlIsReady:


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

+ (void) setWillRegisterWhenGrowlIsReady:(BOOL)flag;
Parameter Descriptions
flag
YES if you want GrowlApplicationBridge to register with Growl when next it is ready; NO 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 method, if it has one). If this method is called with YES, one of those tasks will be to reregister with Growl (in the manner of -reregisterGrowlNotifications).
This attribute is automatically set back to NO (the default) after every GROWL_IS_READY notification.


willRegisterWhenGrowlIsReady


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

+ (BOOL) willRegisterWhenGrowlIsReady;
method result
YES if GrowlApplicationBridge will register with Growl when next it posts GROWL_IS_READY; NO if not.

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