view release on metacpan or  search on metacpan

share/Growl.framework/Versions/A/Headers/GrowlApplicationBridge-Carbon.h  view on Meta::CPAN

	/* 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 formats.
	 *
	 *	 If this is not supplied, Growl will look up your application's icon by
	 *	 its application name.
	 */
	CFDataRef applicationIconData;

	/* Installer display attributes
	 *
	 * These four attributes are used by the Growl installer, if this framework
	 *	supports it.
	 * For any of these being <code>NULL</code>, a localised default will be
	 *	supplied.
	 */

	/*	If this is <code>NULL</code>, Growl will use a default,
	 *	 localized title.
	 *
	 *	 Only used if you're using Growl-WithInstaller.framework. Otherwise,
	 *	 this member is ignored.
	 */
	CFStringRef growlInstallationWindowTitle;
	/*	This information may be as long or short as desired (the
	 *	 window will be sized to fit it).  If Growl is not installed, it will
	 *	 be displayed to the user as an explanation of what Growl is and what
	 *	 it can do in your application.
	 *	 It should probably note that no download is required to install.
	 *
	 *	 If this is <code>NULL</code>, Growl will use a default, localized
	 *	 explanation.
	 *
	 *	 Only used if you're using Growl-WithInstaller.framework. Otherwise,
	 *	 this member is ignored.
	 */
	CFStringRef growlInstallationInformation;
	/*	If this is <code>NULL</code>, Growl will use a default,
	 *	 localized title.
	 *
	 *	 Only used if you're using Growl-WithInstaller.framework. Otherwise,
	 *	 this member is ignored.
	 */
	CFStringRef growlUpdateWindowTitle;
	/*	This information may be as long or short as desired (the
	 *	 window will be sized to fit it).  If an older version of Growl is
	 *	 installed, it will be displayed to the user as an explanation that an
	 *	 updated version of Growl is included in your application and
	 *	 no download is required.
	 *
	 *	 If this is <code>NULL</code>, Growl will use a default, localized
	 *	 explanation.
	 *
	 *	 Only used if you're using Growl-WithInstaller.framework. Otherwise,
	 *	 this member is ignored.
	 */
	CFStringRef growlUpdateInformation;

	/*	This member is provided for use by your retain and release
	 *	 callbacks (see below).
	 *
	 *	 GrowlApplicationBridge never directly uses this member. Instead, it
	 *	 calls your retain callback (if non-<code>NULL</code>) and your release
	 *	 callback (if non-<code>NULL</code>).
	 */
	unsigned referenceCount;

	//Functions. Currently all of these are optional (any of them can be NULL).

	/*	When you call Growl_SetDelegate(newDelegate), it will call
	 *	 oldDelegate->release(oldDelegate), and then it will call
	 *	 newDelegate->retain(newDelegate), and the return value from retain
	 *	 is what will be set as the delegate.
	 *	 (This means that this member works like CFRetain and -[NSObject retain].)
	 *	 This member is optional (it can be <code>NULL</code>).
	 *	 For a delegate allocated with malloc, this member would be
	 *	 <code>NULL</code>.
	 *	@result	A delegate to which GrowlApplicationBridge holds a reference.
	 */
	void *(*retain)(void *);
	/*	When you call Growl_SetDelegate(newDelegate), it will call
	 *	 oldDelegate->release(oldDelegate), and then it will call
	 *	 newDelegate->retain(newDelegate), and the return value from retain
	 *	 is what will be set as the delegate.
	 *	 (This means that this member works like CFRelease and
	 *	  -[NSObject release].)
	 *	 This member is optional (it can be NULL).
	 *	 For a delegate allocated with malloc, this member might be
	 *	 <code>free</code>(3).
	 */
	void (*release)(void *);

	/*	Informs the delegate that Growl (specifically, the GrowlHelperApp) was
	 *	 launched successfully (or was already running). The application can
	 *	 take actions with the knowledge that Growl is installed and functional.
	 */
	void (*growlIsReady)(void);

	/*	Informs the delegate that a Growl notification was clicked. It is only
	 *	 sent for notifications sent with a non-<code>NULL</code> clickContext,
	 *	 so if you want to receive a message when a notification is clicked,
	 *	 clickContext must not be <code>NULL</code> when calling
	 *	 Growl_PostNotification or
	 *	 Growl_NotifyWithTitleDescriptionNameIconPriorityStickyClickContext.
	 */
	void (*growlNotificationWasClicked)(CFPropertyListRef clickContext);

	/*	Informs the delegate that a Growl notification timed out. It is only
	 *	 sent for notifications sent with a non-<code>NULL</code> clickContext,
	 *	 so if you want to receive a message when a notification is clicked,
	 *	 clickContext must not be <code>NULL</code> when calling
	 *	 Growl_PostNotification or
	 *	 Growl_NotifyWithTitleDescriptionNameIconPriorityStickyClickContext.
	 */
	void (*growlNotificationTimedOut)(CFPropertyListRef clickContext);
};

/*!	@struct Growl_Notification
 *	@abstract Structure describing a Growl notification.
 *	@discussion XXX

share/Growl.framework/Versions/A/Headers/GrowlApplicationBridge-Carbon.h  view on Meta::CPAN

*	@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_EXPORT 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.
 */
GROWL_EXPORT void Growl_NotifyWithTitleDescriptionNameIconPriorityStickyClickContext(
 /*inhale*/
	CFStringRef title,
	CFStringRef description,
	CFStringRef notificationName,
	CFDataRef iconData,
	signed int priority,
	Boolean isSticky,
	CFPropertyListRef clickContext);

#pragma mark -

//	@functiongroup	Registering

/*!	@function Growl_RegisterWithDictionary
 *	@abstract	Register your application with Growl without setting a delegate.
 *	@discussion	When you call this function with a dictionary,
 *	 GrowlApplicationBridge registers your application using that dictionary.
 *	 If you pass <code>NULL</code>, 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
 *	 <code>GROWL_APP_NAME</code> 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
 *	 <code>growlIsReady</code> (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.
 *	@result <code>false</code> if registration failed (e.g. if Growl isn't installed).
 */
GROWL_EXPORT Boolean Growl_RegisterWithDictionary(CFDictionaryRef regDict);

/*!	@function	Growl_Reregister
 *	@abstract	Updates your registration with Growl.
 *	@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-<code>NULL</code>.
 *
 *	 This function is now implemented using
 *	 <code>Growl_RegisterWithDictionary</code>.
 */
GROWL_EXPORT void Growl_Reregister(void);

#pragma mark -

/*!	@function	Growl_SetWillRegisterWhenGrowlIsReady
 *	@abstract	Tells GrowlApplicationBridge to register with Growl when Growl
 *	 launches (or not).
 *	@discussion	When Growl has started listening for notifications, it posts a
 *	 <code>GROWL_IS_READY</code> notification on the Distributed Notification
 *	 Center. GrowlApplicationBridge listens for this notification, using it to
 *	 perform various tasks (such as calling your delegate's
 *	 <code>growlIsReady</code> callback, if it has one). If this function is
 *	 called with <code>true</code>, one of those tasks will be to reregister
 *	 with Growl (in the manner of <code>Growl_Reregister</code>).
 *
 *	 This attribute is automatically set back to <code>false</code>
 *	 (the default) after every <code>GROWL_IS_READY</code> notification.
 *	@param	flag	<code>true</code> if you want GrowlApplicationBridge to register with
 *	 Growl when next it is ready; <code>false</code> if not.
 */
GROWL_EXPORT void Growl_SetWillRegisterWhenGrowlIsReady(Boolean flag);
/*!	@function	Growl_WillRegisterWhenGrowlIsReady
 *	@abstract	Reports whether GrowlApplicationBridge will register with Growl
 *	 when Growl next launches.
 *	@result	<code>true</code> if GrowlApplicationBridge will register with
 *	 Growl when next it posts GROWL_IS_READY; <code>false</code> if not.
 */
GROWL_EXPORT Boolean Growl_WillRegisterWhenGrowlIsReady(void);

#pragma mark -

//	@functiongroup	Obtaining registration dictionaries

/*!	@function	Growl_CopyRegistrationDictionaryFromDelegate
 *	@abstract	Asks the delegate for a registration dictionary.
 *	@discussion	If no delegate is set, or if the delegate's