Mac Developer Library

Developer

CoreFoundation Framework Reference CFUserNotification Reference

Options
Deployment Target:

On This Page
Language:

CFUserNotification Reference

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

  • Cancels a user notification dialog.

    Declaration

    Swift

    func CFUserNotificationCancel(_ userNotification: CFUserNotification!) -> Int32

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func CFUserNotificationCheckBoxChecked(_ idx: CFIndex) -> CFOptionFlags

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func CFUserNotificationCreate(_ allocator: CFAllocator!, _ timeout: CFTimeInterval, _ flags: CFOptionFlags, _ error: UnsafeMutablePointer<Int32>, _ dictionary: CFDictionary!) -> CFUserNotification!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • Creates a run loop source for a user notification.

    Declaration

    Swift

    func CFUserNotificationCreateRunLoopSource(_ allocator: CFAllocator!, _ userNotification: CFUserNotification!, _ callout: CFUserNotificationCallBack, _ order: CFIndex) -> CFRunLoopSource!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func CFUserNotificationDisplayAlert(_ timeout: CFTimeInterval, _ flags: CFOptionFlags, _ iconURL: CFURL!, _ soundURL: CFURL!, _ localizationURL: CFURL!, _ alertHeader: CFString!, _ alertMessage: CFString!, _ defaultButtonTitle: CFString!, _ alternateButtonTitle: CFString!, _ otherButtonTitle: CFString!, _ responseFlags: UnsafeMutablePointer<CFOptionFlags>) -> Int32

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func CFUserNotificationDisplayNotice(_ timeout: CFTimeInterval, _ flags: CFOptionFlags, _ iconURL: CFURL!, _ soundURL: CFURL!, _ localizationURL: CFURL!, _ alertHeader: CFString!, _ alertMessage: CFString!, _ defaultButtonTitle: CFString!) -> Int32

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func CFUserNotificationGetResponseDictionary(_ userNotification: CFUserNotification!) -> CFDictionary!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func CFUserNotificationGetResponseValue(_ userNotification: CFUserNotification!, _ key: CFString!, _ idx: CFIndex) -> CFString!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the type identifier for the CFUserNotification opaque type.

    Declaration

    Swift

    func CFUserNotificationGetTypeID() -> CFTypeID

    Objective-C

    CFTypeID CFUserNotificationGetTypeID ( void );

    Return Value

    The type identifier for the CFUserNotification opaque type.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func CFUserNotificationPopUpSelection(_ idx: CFIndex) -> CFOptionFlags

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func CFUserNotificationReceiveResponse(_ userNotification: CFUserNotification!, _ timeout: CFTimeInterval, _ responseFlags: UnsafeMutablePointer<CFOptionFlags>) -> Int32

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func CFUserNotificationSecureTextField(_ idx: CFIndex) -> CFOptionFlags

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func CFUserNotificationUpdate(_ userNotification: CFUserNotification!, _ timeout: CFTimeInterval, _ flags: CFOptionFlags, _ dictionary: CFDictionary!) -> Int32

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

Callbacks

  • Callback invoked when an asynchronous user notification dialog is dismissed.

    Declaration

    Swift

    typealias CFUserNotificationCallBack = CFunctionPointer<((CFUserNotification!, CFOptionFlags) -> Void)>

    Objective-C

    typedef void (*CFUserNotificationCallBack) ( 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.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

Data Types

Miscellaneous

  • A reference to a user notification object.

    Declaration

    Swift

    typealias CFUserNotificationRef = CFUserNotification

    Objective-C

    typedef struct __CFUserNotification *CFUserNotificationRef;

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

Constants

Miscellaneous

  • Flags identifying the seriousness of a user notification.

    Declaration

    Swift

    var kCFUserNotificationStopAlertLevel: Int { get } var kCFUserNotificationNoteAlertLevel: Int { get } var kCFUserNotificationCautionAlertLevel: Int { get } var kCFUserNotificationPlainAlertLevel: Int { get }

    Objective-C

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

    Constants

    • kCFUserNotificationStopAlertLevel

      kCFUserNotificationStopAlertLevel

      The notification is very serious.

      A stop icon is displayed by default.

      Available in OS X v10.0 and later.

    • kCFUserNotificationNoteAlertLevel

      kCFUserNotificationNoteAlertLevel

      The notification is not very serious.

      A note icon is displayed by default.

      Available in OS X v10.0 and later.

    • kCFUserNotificationCautionAlertLevel

      kCFUserNotificationCautionAlertLevel

      The notification is somewhat serious.

      A caution icon is displayed by default.

      Available in OS X v10.0 and later.

    • kCFUserNotificationPlainAlertLevel

      kCFUserNotificationPlainAlertLevel

      The notification is not serious.

      An information icon is displayed by default.

      Available in OS X v10.0 and later.

    Discussion

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

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

    Declaration

    Swift

    var kCFUserNotificationDefaultResponse: Int { get } var kCFUserNotificationAlternateResponse: Int { get } var kCFUserNotificationOtherResponse: Int { get } var kCFUserNotificationCancelResponse: Int { get }

    Objective-C

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

    Constants

    • kCFUserNotificationDefaultResponse

      kCFUserNotificationDefaultResponse

      The default button was pressed.

      Available in OS X v10.0 and later.

    • kCFUserNotificationAlternateResponse

      kCFUserNotificationAlternateResponse

      The alternate button was pressed.

      Available in OS X v10.0 and later.

    • kCFUserNotificationOtherResponse

      kCFUserNotificationOtherResponse

      The third button was pressed.

      Available in OS X v10.0 and later.

    • kCFUserNotificationCancelResponse

      kCFUserNotificationCancelResponse

      No button was pressed and the notification timed out.

      Available in OS X v10.0 and later.

    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.

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

    Declaration

    Swift

    var kCFUserNotificationNoDefaultButtonFlag: Int { get } var kCFUserNotificationUseRadioButtonsFlag: Int { get }

    Objective-C

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

    Constants

    • kCFUserNotificationNoDefaultButtonFlag

      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 OS X v10.0 and later.

    • kCFUserNotificationUseRadioButtonsFlag

      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 OS X v10.0 and later.

    Discussion

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

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

    Declaration

    Swift

    let kCFUserNotificationIconURLKey: CFString! let kCFUserNotificationSoundURLKey: CFString! let kCFUserNotificationLocalizationURLKey: CFString! let kCFUserNotificationAlertHeaderKey: CFString! let kCFUserNotificationAlertMessageKey: CFString! let kCFUserNotificationDefaultButtonTitleKey: CFString! let kCFUserNotificationAlternateButtonTitleKey: CFString! let kCFUserNotificationOtherButtonTitleKey: CFString! let kCFUserNotificationProgressIndicatorValueKey: CFString! let kCFUserNotificationPopUpTitlesKey: CFString! let kCFUserNotificationTextFieldTitlesKey: CFString! let kCFUserNotificationCheckBoxTitlesKey: CFString! let kCFUserNotificationTextFieldValuesKey: CFString! let kCFUserNotificationPopUpSelectionKey: CFString!

    Objective-C

    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

      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 OS X v10.0 and later.

    • kCFUserNotificationSoundURLKey

      kCFUserNotificationSoundURLKey

      A file URL pointing to a sound that will be played when the alert appears.

      Available in OS X v10.0 and later.

    • kCFUserNotificationLocalizationURLKey

      kCFUserNotificationLocalizationURLKey

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

      Available in OS X v10.0 and later.

    • kCFUserNotificationAlertHeaderKey

      kCFUserNotificationAlertHeaderKey

      The title of the notification dialog.

      This key is required.

      Available in OS X v10.0 and later.

    • kCFUserNotificationAlertMessageKey

      kCFUserNotificationAlertMessageKey

      The message string to display in the dialog.

      Available in OS X v10.0 and later.

    • kCFUserNotificationDefaultButtonTitleKey

      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 OS X v10.0 and later.

    • kCFUserNotificationAlternateButtonTitleKey

      kCFUserNotificationAlternateButtonTitleKey

      The title of an optional alternate button.

      Available in OS X v10.0 and later.

    • kCFUserNotificationOtherButtonTitleKey

      kCFUserNotificationOtherButtonTitleKey

      The title of an optional third button.

      Available in OS X v10.0 and later.

    • kCFUserNotificationProgressIndicatorValueKey

      kCFUserNotificationProgressIndicatorValueKey

      A value to indicate the progress of an operation.

      The value is a number between 0 and 1, for a “definite” progress indicator, or a Boolean for an “indefinite” progress indicator.

      Available in OS X v10.0 and later.

    • kCFUserNotificationPopUpTitlesKey

      kCFUserNotificationPopUpTitlesKey

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

      The array cannot have more than 256 elements.

      Available in OS X v10.0 and later.

    • kCFUserNotificationTextFieldTitlesKey

      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 OS X v10.0 and later.

    • kCFUserNotificationCheckBoxTitlesKey

      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 OS X v10.0 and later.

    • kCFUserNotificationTextFieldValuesKey

      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 OS X v10.0 and later.

    • kCFUserNotificationPopUpSelectionKey

      kCFUserNotificationPopUpSelectionKey

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

      Available in OS X v10.3 and later.

    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.