# 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)