growlapplicationbridge-carbon.h

lumaqq

	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);
};

#pragma mark -
#pragma mark Easy initialisers

/*!	@defined	InitGrowlDelegate
 *	@abstract	Callable macro. Initializes a Growl delegate structure to defaults.
 *	@discussion	Call with a pointer to a struct Growl_Delegate. All of the
 *	 members of the structure will be set to 0 or <code>NULL</code>, except for
 *	 size (which will be set to <code>sizeof(struct Growl_Delegate)</code>) and
 *	 referenceCount (which will be set to 1).
 */
#define InitGrowlDelegate(delegate) \
	do { \
		if (delegate) { \
			(delegate)->size = sizeof(struct Growl_Delegate); \
			(delegate)->applicationName = NULL; \
			(delegate)->registrationDictionary = NULL; \
			(delegate)->applicationIconData = NULL; \
			(delegate)->growlInstallationWindowTitle = NULL; \
			(delegate)->growlInstallationInformation = NULL; \
			(delegate)->growlUpdateWindowTitle = NULL; \
			(delegate)->growlUpdateInformation = NULL; \
			(delegate)->referenceCount = 1U; \
			(delegate)->retain = NULL; \
			(delegate)->release = NULL; \
			(delegate)->growlIsReady = NULL; \
			(delegate)->growlNotificationWasClicked = NULL; \
			(delegate)->growlNotificationTimedOut = NULL; \
		} \
	} while(0)

/*!	@defined	InitGrowlNotification
 *	@abstract	Callable macro. Initializes a Growl notification structure to defaults.
 *	@discussion	Call with a pointer to a struct Growl_Notification. All of
 *	 the members of the structure will be set to 0 or <code>NULL</code>, except
 *	 for size (which will be set to
 *	<code>sizeof(struct Growl_Notification)</code>).
 */
#define InitGrowlNotification(notification) \
	do { \
		if (notification) { \
			(notification)->size = sizeof(struct Growl_Notification); \
			(notification)->name = NULL; \
			(notification)->title = NULL; \
			(notification)->description = NULL; \
			(notification)->iconData = NULL; \
			(notification)->priority = 0; \
			(notification)->reserved = 0U; \
			(notification)->isSticky = false; \
			(notification)->clickContext = NULL; \
		} \
	} while(0)

#pragma mark -
#pragma mark Public API

//	@functiongroup	Managing the Growl delegate

/*!	@function	Growl_SetDelegate
 *	@abstract	Replaces the current Growl delegate with a new one, or removes
 *	 the Growl delegate.
 *	@param	newDelegate
 *	@result	Returns false and does nothing else if a pointer that was passed in
 *	 is unsatisfactory (because it is non-<code>NULL</code>, but at least one
 *	 required member of it is <code>NULL</code>). Otherwise, sets or unsets the
 *	 delegate and returns true.
 *	@discussion	When <code>newDelegate</code> is non-<code>NULL</code>, sets
 *	 the delegate to <code>newDelegate</code>. When it is <code>NULL</code>,
 *	 the current delegate will be unset, and no delegate will be in place.
 *
 *	 It is legal for <code>newDelegate</code> to be the current delegate;
 *	 nothing will happen, and Growl_SetDelegate will return true. It is also
 *	 legal for it to be <code>NULL</code>, 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-<code>NULL</code>. If
 *	 <code>newDelegate</code> is non-<code>NULL</code>, Growl_SetDelegate will
 *	 call <code>newDelegate->retain</code>, 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.
 */
Boolean Growl_SetDelegate(struct Growl_Delegate *newDelegate);

/*!	@function	Growl_GetDelegate
 *	@abstract	Returns the current Growl delegate, if any.
 *	@result	The current Growl delegate.
 *	@discussion	Returns the last pointer passed into Growl_SetDelegate, or
 *	 <code>NULL</code> 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.
 */
struct Growl_Delegate *Growl_GetDelegate(void);

#pragma mark -

//	@functiongroup	Posting Growl notifications

/*!	@function	Growl_PostNotification
 *	@abstract	Posts a Growl notification.
 *	@param	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
 *	 <code>NULL</code> (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.
 */
void Growl_PostNotification(const struct Growl_Notification *notification);

/*!	@function Growl_PostNotificationWithDictionary
*	@abstract	Notifies using a userInfo dictionary suitable for passing to
*	 CFDistributedNotificationCenter.
*	@param	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.
*/
void Growl_PostNotificationWithDictionary(CFDictionaryRef userInfo);

/*!	@function	Growl_NotifyWithTitleDescriptionNameIconPriorityStickyClickContext
 *	@abstract	Posts a Growl notification using parameter values.
 *	@param	title	The title of the notification.
 *	@param	description	The description of the notification.
 *	@param	notificationName	The name of the notification as listed in the
 *	 registration dictionary.
 *	@param	iconData	Data representing a notification icon. Can be <code>NULL</code>.
 *	@param	priority	The priority of the notification (-2 to +2, with -2
 *	 being Very Low and +2 being Very High).
 *	@param	isSticky	If true, requests that this notification wait for a
 *	 response from the user.
 *	@param	clickContext	An object to pass to the clickCallback, if any. Can
 *	 be <code>NULL</code>, 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
 *	 10.3, this includes the .icns, TIFF, JPEG, GIF, PNG, PDF, and PICT formats.
 */
void Growl_NotifyWithTitleDescriptionNameIconPriorityStickyClickContext(
 /*inhale*/
	CFStringRef title,
	CFStringRef description,
	CFStringRef notificationName,
	CFDataRef iconData,
	signed int priority,
	Boolean isSticky,
	CFPropertyListRef clickContext);

#pragma mark -

//	@functiongroup	Registering