Next Page > Hide TOC

CFUserNotification Reference

Overview

A CFUserNotification object presents a simple dialog on the screen and optionally receives feedback from the user. The contents of the dialog can include a header, a message, an icon, text fields, a pop-up button, radio buttons or checkboxes, and up to three ordinary buttons. Use CFUserNotification in processes that do not otherwise have user interfaces, but may need occasional interaction with the user.

You create a user notification with the CFUserNotificationCreate function. You pass in a dictionary whose keys describe the items to place into the dialog. (See “Dialog Description Keys” for the list of keys.) A set of flags passed to the function determines, among other things, whether secure text fields are used (such as for password fields), whether radio buttons or checkboxes are used, and which of these buttons are checked by default. You can also specify a timeout for the dialog, in which case the dialog cancels itself if the user does not respond in the allotted time period.

A user notification displays its dialog as soon as it is created. If any reply is required, it may be awaited in one of two ways: either synchronously, using CFUserNotificationReceiveResponse, or asynchronously, using a run loop source created with CFUserNotificationCreateRunLoopSource. CFUserNotificationReceiveResponse has a timeout parameter that determines how long it will block (zero meaning indefinitely) and it may be called as many times as necessary until a response arrives. If a user notification has not yet received a response, it may be updated with new information or it may be cancelled. User notifications may not be reused.

CFUserNotification provides two convenience functions, CFUserNotificationDisplayNotice and CFUserNotificationDisplayAlert, to display very basic dialogs that either require no response from the user or require only a single button to be pressed, respectively.

Functions

CFUserNotificationCancel

Cancels a user notification dialog.

SInt32 CFUserNotificationCancel (
   CFUserNotificationRef userNotification
);

Parameters

userNotification

The user notification to cancel.

Return Value

0 if the cancel was successful; a non-0 value otherwise.

Discussion

You must cancel a user notification if you want to remove its dialog from the screen before the user dismisses it. It is not sufficient to just release the object.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

CFUserNotificationCheckBoxChecked

Returns a flag used to set or test a checkbox’s state.

CFOptionFlags CFUserNotificationCheckBoxChecked (
   CFIndex i
);

Parameters

idx

The index of the checkbox to set or test. The index corresponds to the order in which the checkbox titles are listed in the kCFUserNotificationCheckBoxTitlesKey array of the user notification’s description dictionary. idx must be in the range 0 to 7.

Return Value

A flag that can be used either to set the state of a checkbox when creating a user notification with CFUserNotificationCreate or to test a checkbox’s state returned in a user notification’s response flags, such as from CFUserNotificationReceiveResponse, when the notification dialog is dismissed.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

CFUserNotificationCreate

Creates a CFUserNotification object and displays its notification dialog on screen.

CFUserNotificationRef CFUserNotificationCreate (
   CFAllocatorRef allocator,
   CFTimeInterval timeout,
   CFOptionFlags flags,
   SInt32 *error,
   CFDictionaryRef dictionary
);

Parameters

allocator

The allocator to use to allocate memory for the new object. Pass NULL or kCFAllocatorDefault to use the current default allocator.

timeout

The time to wait before the notification dialog dismisses itself if the user does not respond. If 0, the notification never times out.

flags

A set of flags describing the type of notification to display. These flags specify an alert level for the notification (see Alert Levels), determine whether radio buttons or checkboxes are to be used (see Button Flags), specify which, if any, of these buttons are checked by default (see CFUserNotificationCheckBoxChecked), specify whether any of the text fields are to be secure text fields (see CFUserNotificationSecureTextField), and determine which element of a pop-up menu, if present, should be selected by default (see CFUserNotificationPopUpSelection). Combine these flags together by performing a bitwise-OR operation with all the individual flags.

error

On return contains an integer error code. If 0, the user notification was successfully created and displayed.

dictionary

A description of the elements to display in the notification dialog. The possible keys are listed in “Dialog Description Keys.” The dictionary must contain a value for the key kCFUserNotificationAlertHeaderKey, but the other keys are optional.

Return Value

The new CFUserNotification object. Ownership follows the Create Rule.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

CFUserNotificationCreateRunLoopSource

Creates a run loop source for a user notification.

CFRunLoopSourceRef CFUserNotificationCreateRunLoopSource (
   CFAllocatorRef allocator,
   CFUserNotificationRef userNotification,
   CFUserNotificationCallBack callout,
   CFIndex order
);

Parameters

allocator

The allocator to use to allocate memory for the new object. Pass NULL or kCFAllocatorDefault to use the current default allocator.

userNotification

The user notification to use.

callout

The callback function to invoke when the user notification dialog is dismissed.

order

A priority index indicating the order in which run loop sources are processed. User notifications currently ignore this parameter. Pass 0 for this value.

Return Value

The new CFRunLoopSource object. Ownership follows the Create Rule.

Discussion

A run loop source needs to be added to a run loop before it can fire and call its callback function. To add the source to a run loop, use CFRunLoopAddSource.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

CFUserNotificationDisplayAlert

Displays a user notification dialog and waits for a user response.

SInt32 CFUserNotificationDisplayAlert (
   CFTimeInterval timeout,
   CFOptionFlags flags,
   CFURLRef iconURL,
   CFURLRef soundURL,
   CFURLRef localizationURL,
   CFStringRef alertHeader,
   CFStringRef alertMessage,
   CFStringRef defaultButtonTitle,
   CFStringRef alternateButtonTitle,
   CFStringRef otherButtonTitle,
   CFOptionFlags *responseFlags
);

Parameters

timeout

The amount of time to wait for the user to dismiss the notification dialog before the dialog dismisses itself. Pass 0 to have the dialog never time out.

flags

A set of flags describing the type of notification dialog to display. The value is normally just the alert level from Alert Levels. If you don’t want a default button displayed, perform a bitwise-OR operation with the alert level and the constant kCFUserNotificationNoDefaultButtonFlag.

iconURL

A file URL pointing to the icon to display in the dialog. If NULL, a default icon is used based on the notification’s alert level specified in flags.

soundURL

Not used.

localizationURL

A file URL pointing to a bundle that contains localized versions of the strings displayed in the dialog. Can be NULL.

alertHeader

The title of the notification dialog. Cannot be NULL.

alertMessage

The message string to display in the dialog. Can be NULL.

defaultButtonTitle

The title of the default button. If NULL, the string OK is used.

alternateButtonTitle

The title of an optional alternate button. Can be NULL.

otherButtonTitle

The title of an optional third button. Can be NULL.

responseFlags

On return, contains flags identifying how the notification was dismissed. See Response Codes for details.

Return Value

0 if the cancel was successful; a non-0 value otherwise.

Discussion

This function blocks the current thread’s execution until the dialog is dismissed, either by the user or by timing out.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

CFUserNotificationDisplayNotice

Displays a user notification dialog that does not need a user response.

SInt32 CFUserNotificationDisplayNotice (
   CFTimeInterval timeout,
   CFOptionFlags flags,
   CFURLRef iconURL,
   CFURLRef soundURL,
   CFURLRef localizationURL,
   CFStringRef alertHeader,
   CFStringRef alertMessage,
   CFStringRef defaultButtonTitle
);

Parameters

timeout

The amount of time to wait for the user to dismiss the notification dialog before the dialog dismisses itself. Pass 0 to have the dialog never time out.

flags

A set of flags describing the type of notification dialog to display. The value is normally just the alert level from Alert Levels. If you don’t want a default button displayed, perform a bitwise-OR operation with the alert level and the constant kCFUserNotificationNoDefaultButtonFlag.

iconURL

A file URL pointing to the icon to display in the dialog. If NULL, a default icon is used based on the notification’s alert level specified in flags.

soundURL

Not used.

localizationURL

A file URL pointing to a bundle that contains localized versions of the strings displayed in the dialog. Can be NULL.

alertHeader

The title of the notification dialog. Cannot be NULL.

alertMessage

The message string to display in the dialog. Can be NULL.

defaultButtonTitle

The title of the default button. If NULL, the string OK is used.

Return Value

0 if the cancel was successful; a non-0 value otherwise.

Discussion

This function returns immediately. It does not wait for a user response after displaying the dialog.

Availability

• Available in Mac OS X v10.0 and later.

Related Sample Code

• X11CallCarbonAndCocoa

Declared In

CFUserNotificationGetResponseDictionary

Returns the dictionary containing all the text field values from a dismissed notification dialog.

CFDictionaryRef CFUserNotificationGetResponseDictionary (
   CFUserNotificationRef userNotification
);

Parameters

userNotification

The user notification to use.

Return Value

A dictionary holding the values of all the text fields in userNotification when it was dismissed. The values are in an array stored with the key kCFUserNotificationTextFieldValuesKey. Ownership follows the Get Rule.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

CFUserNotificationGetResponseValue

Extracts the values of the text fields from a dismissed notification dialog.

CFStringRef CFUserNotificationGetResponseValue (
   CFUserNotificationRef userNotification,
   CFStringRef key,
   CFIndex idx
);

Parameters

userNotification

The user notification to use.

key

The dictionary key identifying the text fields to use. Currently, only kCFUserNotificationTextFieldValuesKey is supported.

idx

The index of the text field value to return. The index corresponds to the order in which text fields are listed in the kCFUserNotificationTextFieldTitlesKey array in the user notification’s description dictionary.

Return Value

The value of the text field identified by key and idx. Ownership follows the Get Rule.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

CFUserNotificationGetTypeID

Returns the type identifier for the CFUserNotification opaque type.

CFTypeID CFUserNotificationGetTypeID (
   void
);

Return Value

The type identifier for the CFUserNotification opaque type.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

CFUserNotificationPopUpSelection

Returns a flag used to set the selected element of a pop-up menu.

CFOptionFlags CFUserNotificationPopUpSelection (
   CFIndex n
);

Parameters

idx

The index of the pop-up menu element to select. The index corresponds to the order in which the pop-up menu elements are listed in the kCFUserNotificationPopUpTitlesKey array of the user notification’s description dictionary. idx must be in the range 0 to 255.

Return Value

A flag that can be used to set the selected element of a pop-up menu when creating a user notification with CFUserNotificationCreate.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

CFUserNotificationReceiveResponse

Waits for the user to respond to a notification or for the notification to time out.

SInt32 CFUserNotificationReceiveResponse (
   CFUserNotificationRef userNotification,
   CFTimeInterval timeout,
   CFOptionFlags *responseFlags
);

Parameters

userNotification

The user notification to use.

timeout

The amount of time to wait for the user to respond to userNotification or for the notification to time out. If neither happens before timeout passes, this function returns a non-0 value. If timeout is 0, the function blocks until the user notification is dismissed.

responseFlags

On return, contains flags identifying how the notification was dismissed, the state of any checkboxes, and the selected element of the pop-up menu. Bits 0-1 of the value hold an identifier for the button pressed by the user (see Response Codes). Extract the identifier by performing a bitwise-AND operation with 0x3. Bits 8-15 of responseFlags hold the state of up to 8 checkboxes or radio buttons, if present. Extract the flags by performing bitwise-AND operations with the return value of CFUserNotificationCheckBoxChecked. Bits 24-31 hold the index number of the element selected in a pop-up menu, if present. Extract the index by performing a 24-bit right shift: responseFlags >> 24.

Return Value

0 if the cancel was successful; a non-0 value otherwise.

Discussion

Use this function to poll a user notification for a user response. You can call it any number of times on the same user notification.

To avoid polling and blocking your thread’s execution, you can create a run loop source for the user notification with CFUserNotificationCreateRunLoopSource. You will then receive a callback when the dialog is dismissed.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

CFUserNotificationSecureTextField

Returns a flag used to set the secure state of a text field.

CFOptionFlags CFUserNotificationSecureTextField (
   CFIndex i
);

Parameters

idx

The index of the text field to make secure. The index corresponds to the order in which the text fields are listed in the kCFUserNotificationTextFieldTitlesKey array of the user notification’s description dictionary. idx must be in the range 0 to 7.

Return Value

A flag that can be used to set the secure state of a text field when creating a user notification with CFUserNotificationCreate.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

CFUserNotificationUpdate

Updates a displayed user notification dialog with new user interface information.

SInt32 CFUserNotificationUpdate (
   CFUserNotificationRef userNotification,
   CFTimeInterval timeout,
   CFOptionFlags flags,
   CFDictionaryRef dictionary
);

Parameters

userNotification

The user notification to update.

timeout

The new timeout value for the dialog.

flags

A set of flags describing the type of notification to display. See CFUserNotificationCreate for details.

dictionary

A description of the elements to display in the notification dialog. The possible keys are listed in “Dialog Description Keys.”

Return Value

0 if the cancel was successful; a non-0 value otherwise.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

Callbacks

CFUserNotificationCallBack

Callback invoked when an asynchronous user notification dialog is dismissed.

typedef void (*CFUserNotificationCallBack) (
   CFUserNotificationRef userNotification,
   CFOptionFlags responseFlags
);

If you name your function MyCallBack, you would declare it like this:

void MyCallBack (
   CFUserNotificationRef userNotification,
   CFOptionFlags responseFlags
);

Parameters

userNotification

The user notification that was dismissed.

responseFlags

On return, contains flags identifying how the notification was dismissed, the state of any checkboxes, and the selected item of the pop-up menu. See CFUserNotificationReceiveResponse for details.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

Data Types

CFUserNotificationRef

A reference to a user notification object.

typedef struct __CFUserNotification *CFUserNotificationRef;

Availability

• Available in Mac OS X v10.0 and later.

Declared In

Constants

Alert Levels

Flags identifying the seriousness of a user notification.

enum {
   kCFUserNotificationStopAlertLevel = 0,
   kCFUserNotificationNoteAlertLevel = 1,
   kCFUserNotificationCautionAlertLevel = 2,
   kCFUserNotificationPlainAlertLevel= 3
};

Constants

kCFUserNotificationStopAlertLevel

The notification is very serious.

A stop icon is displayed by default.

Available in Mac OS X v10.0 and later.

Declared in CFUserNotification.h.

kCFUserNotificationNoteAlertLevel

The notification is not very serious.

A note icon is displayed by default.

Available in Mac OS X v10.0 and later.

Declared in CFUserNotification.h.

kCFUserNotificationCautionAlertLevel

The notification is somewhat serious.

A caution icon is displayed by default.

Available in Mac OS X v10.0 and later.

Declared in CFUserNotification.h.

kCFUserNotificationPlainAlertLevel

The notification is not serious.

An information icon is displayed by default.

Available in Mac OS X v10.0 and later.

Declared in CFUserNotification.h.

Discussion

If you specify an icon to display in the dialog, this icon overrides the default icon used for each alert level.

Response Codes

Response codes identifying the button that was pressed to dismiss a notification dialog.

enum {
   kCFUserNotificationDefaultResponse = 0,
   kCFUserNotificationAlternateResponse = 1,
   kCFUserNotificationOtherResponse = 2,
   kCFUserNotificationCancelResponse = 3
};

Constants

kCFUserNotificationDefaultResponse

The default button was pressed.

Available in Mac OS X v10.0 and later.

Declared in CFUserNotification.h.

kCFUserNotificationAlternateResponse

The alternate button was pressed.

Available in Mac OS X v10.0 and later.

Declared in CFUserNotification.h.

kCFUserNotificationOtherResponse

The third button was pressed.

Available in Mac OS X v10.0 and later.

Declared in CFUserNotification.h.

kCFUserNotificationCancelResponse

No button was pressed and the notification timed out.

Available in Mac OS X v10.0 and later.

Declared in CFUserNotification.h.

Discussion

To extract this value from the response flags of a dismissed notification (such as returned by CFUserNotificationReceiveResponse), you must perform a bitwise-AND operation between the returned response flags and 0x3 before comparing the value to these constants.

Button Flags

Flags that alter the display of buttons in a user notification dialog.

enum {
   kCFUserNotificationNoDefaultButtonFlag = (1 << 5),
   kCFUserNotificationUseRadioButtonsFlag = (1 << 6)
};

Constants

kCFUserNotificationNoDefaultButtonFlag

Displays the dialog without the default, alternate, or other buttons.

The dialog remains on screen until it times out or you cancel it with CFUserNotificationCancel. If you provide a title for the default button in the user notification’s description dictionary, this flag is ignored and buttons show up normally.

Available in Mac OS X v10.0 and later.

Declared in CFUserNotification.h.

kCFUserNotificationUseRadioButtonsFlag

Creates a group of radio buttons instead of checkboxes for the elements in the kCFUserNotificationCheckBoxTitlesKey array in the user notification’s description dictionary.

Available in Mac OS X v10.0 and later.

Declared in CFUserNotification.h.

Discussion

You specify these flags when you create the user notification with CFUserNotificationCreate.

Dialog Description Keys

Keys used in a user notification’s description dictionary, which describes the contents of the notification dialog to display.

const CFStringRef kCFUserNotificationIconURLKey;
const CFStringRef kCFUserNotificationSoundURLKey;
const CFStringRef kCFUserNotificationLocalizationURLKey;
const CFStringRef kCFUserNotificationAlertHeaderKey;
const CFStringRef kCFUserNotificationAlertMessageKey;
const CFStringRef kCFUserNotificationDefaultButtonTitleKey;
const CFStringRef kCFUserNotificationAlternateButtonTitleKey;
const CFStringRef kCFUserNotificationOtherButtonTitleKey;
const CFStringRef kCFUserNotificationProgressIndicatorValueKey;
const CFStringRef kCFUserNotificationPopUpTitlesKey;
const CFStringRef kCFUserNotificationTextFieldTitlesKey;
const CFStringRef kCFUserNotificationCheckBoxTitlesKey;
const CFStringRef kCFUserNotificationTextFieldValuesKey;
const CFStringRef kCFUserNotificationPopUpSelectionKey

Constants

kCFUserNotificationIconURLKey

A file URL pointing to the icon to display in the dialog.

If absent, a default icon based on the alert level is used.

Available in Mac OS X v10.0 and later.

Declared in CFUserNotification.h.

kCFUserNotificationSoundURLKey

Not used.

Available in Mac OS X v10.0 and later.

Declared in CFUserNotification.h.

kCFUserNotificationLocalizationURLKey

A file URL pointing to a bundle that contains localized versions of the strings displayed in the dialog.

Available in Mac OS X v10.0 and later.

Declared in CFUserNotification.h.

kCFUserNotificationAlertHeaderKey

The title of the notification dialog.

This key is required.

Available in Mac OS X v10.0 and later.

Declared in CFUserNotification.h.

kCFUserNotificationAlertMessageKey

The message string to display in the dialog.

Available in Mac OS X v10.0 and later.

Declared in CFUserNotification.h.

kCFUserNotificationDefaultButtonTitleKey

The title of the default button.

If absent and the dialog is not being created with the kCFUserNotificationNoDefaultButtonFlag flag, a default button title of OK is used.

Available in Mac OS X v10.0 and later.

Declared in CFUserNotification.h.

kCFUserNotificationAlternateButtonTitleKey

The title of an optional alternate button.

Available in Mac OS X v10.0 and later.

Declared in CFUserNotification.h.

kCFUserNotificationOtherButtonTitleKey

The title of an optional third button.

Available in Mac OS X v10.0 and later.

Declared in CFUserNotification.h.

kCFUserNotificationProgressIndicatorValueKey

Not used.

Available in Mac OS X v10.0 and later.

Declared in CFUserNotification.h.

kCFUserNotificationPopUpTitlesKey

The list of strings to display in a pop-up menu.

The array cannot have more than 256 elements.

Available in Mac OS X v10.0 and later.

Declared in CFUserNotification.h.

kCFUserNotificationTextFieldTitlesKey

The list of titles for all the text fields to display.

If only one text field is to be displayed, you can pass its title string directly without putting it into an array first.

Available in Mac OS X v10.0 and later.

Declared in CFUserNotification.h.

kCFUserNotificationCheckBoxTitlesKey

The list of titles for all the checkboxes or radio buttons to display.

The array cannot have more than 8 elements. If only one checkbox is to be displayed, you can pass its title string directly without putting it into an array first.

Available in Mac OS X v10.0 and later.

Declared in CFUserNotification.h.

kCFUserNotificationTextFieldValuesKey

The list of values to put into the text fields. If only one text field is to be displayed, you can pass its value string directly without putting it into an array first.

Available in Mac OS X v10.0 and later.

Declared in CFUserNotification.h.

kCFUserNotificationPopUpSelectionKey

The item that was selected from a pop-up menu.

Available in Mac OS X v10.3 and later.

Declared in CFUserNotification.h.

Discussion

When creating the user notification with CFUserNotificationCreate, the description dictionary must have a value for kCFUserNotificationAlertHeaderKey. All other keys are optional.

The button title keys must be given in right-to-left order—you therefore must use the kCFUserNotificationDefaultButtonTitleKey constant for the rightmost button even if it is conceptually not a "default" button (for example, if you want a single "Cancel" button that should not have color, should not pulse, and should not have return for a key equivalent). If, however, you set the kCFUserNotificationNoDefaultButtonFlag, the rightmost button does not behave as a default button (although it will still be the "default" button in the sense of using kCFUserNotificationDefaultButtonTitleKey and kCFUserNotificationDefaultResponse). The following code fragment shows how you can create a notification that contains a single "Cancel" button that does not behave as a default button.

const void* keys[] = {kCFUserNotificationAlertHeaderKey,

                      kCFUserNotificationProgressIndicatorValueKey,

                      kCFUserNotificationDefaultButtonTitleKey};

const void* values[] = {CFSTR("Progress"),

                        kCFBooleanTrue,

                        CFSTR("Cancel")};

CFDictionaryRef parameters = CFDictionaryCreate(0, keys, values,

        sizeof(keys)/sizeof(*keys), &kCFTypeDictionaryKeyCallBacks,

        &kCFTypeDictionaryValueCallBacks);

SInt32 err = 0;

CFUserNotificationCreate(kCFAllocatorDefault, 0,

        kCFUserNotificationPlainAlertLevel | kCFUserNotificationNoDefaultButtonFlag,

        &err, parameters);

If you set the kCFUserNotificationNoDefaultButtonFlag flag and do not specify a value for kCFUserNotificationDefaultButtonTitleKey, the notification will have no buttons.

Next Page > Hide TOC