Alerts
PBAlert
Opaque object handle:
This is a subclass of PBWindow. You can safely cast from PBAlert to PBWindow. To cast from PBWindow to PBAlert, call PBAlertCast; this performs a runtime assertion to check the cast is possible. This function is thread-safe.
This object maintains an internal reference count. When the reference count reaches zero, the object will be automatically deallocated. To increment the reference count, call PBElementRetain; to decrement the reference count, call PBElementRelease. These functions are thread-safe.
PBAlertResponse
Enumeration/bitset of type uint32_t:
Constants
PBAlertResponse_PRIMARY
PBAlertResponse_PRIMARY = 1
PBAlertResponse_SECONDARY
PBAlertResponse_SECONDARY = 2
PBAlertResponse_TERTIARY
PBAlertResponse_TERTIARY = 3
PBAlertFlags
Enumeration/bitset of type uint32_t:
Constants
PBAlert_RESIZABLE_BY_USER
PBAlert_RESIZABLE_BY_USER = 1<<0
Reserved.
Or any of the values from PBElementFlags.
PBAlertConfiguration
Structure:
Fields
message (referenced string):
description (referenced string):
suppressionKey (referenced string): Reserved.
primaryButtonLabel (referenced string):
secondaryButtonLabel (referenced string):
tertiaryButtonLabel (referenced string):
primaryButtonAccessKey (PBKeyCode):
secondaryButtonAccessKey (PBKeyCode):
tertiaryButtonAccessKey (PBKeyCode):
flags (PBAlertFlags):
width (int32_t
):
height (int32_t
):
icon (nullable referenced PBImage):
PBAlertCompletionHandler
Callback:
Syntax (C/C++)
bool PBAlertCompletionHandler(PBAlertRef alert, PBAlertResponse response);
You can create a callback of this type from a function pointer with the above signature using PBAlertCompletionHandler_Make
.
Syntax (Python)
AlertCompletionHandler(alert, response) -> (closeAlert)
Parameters and Return Values
[in] alert (referenced PBAlert):
[in] response (PBAlertResponse):
[out] closeAlert (bool
):
PBAlertCreate
Function:
Syntax (C/C++)
PBAlertPtr _Nullable PBAlertCreate(PBWindowRef _Nullable owner,
PBAlertConfiguration configuration, PBAlertCompletionHandler completionHandler);
Syntax (Python)
AlertCreate(owner, configuration, completionHandler) -> (alert)
Parameters and Return Values
[in] owner (nullable referenced PBWindow):
[in] configuration (PBAlertConfiguration):
[in] completionHandler (PBAlertCompletionHandler):
[out] alert (nullable owned PBAlert):
PBAlertComplete
Function:
Syntax (C/C++)
bool PBAlertComplete(PBAlertRef alert, PBAlertResponse response);
Syntax (Python)
AlertComplete(alert, response) -> (alertClosed)
Parameters and Return Values
[in] alert (referenced PBAlert):
[in] response (PBAlertResponse):
[out] alertClosed (bool
):
PBAlertSetResponseDisabled
Function:
Syntax (C/C++)
void PBAlertSetResponseDisabled(PBAlertRef alert, PBAlertResponse response,
bool disabled);
Syntax (Python)
AlertSetResponseDisabled(alert, response, disabled)
Parameters and Return Values
[in] alert (referenced PBAlert):
[in] response (PBAlertResponse):
[in] disabled (bool
):
PBAlertIsResponseDisabled
Function:
Syntax (C/C++)
bool PBAlertIsResponseDisabled(PBAlertRef alert, PBAlertResponse response);
Syntax (Python)
AlertIsResponseDisabled(alert, response) -> (disabled)
Parameters and Return Values
[in] alert (referenced PBAlert):
[in] response (PBAlertResponse):
[out] disabled (bool
):
PBAlertSetMessage
Function:
Syntax (C/C++)
void PBAlertSetMessage(PBAlertRef alert, PBTextDocumentRef _Nullable newMessage);
Syntax (Python)
AlertSetMessage(alert, newMessage)
Parameters and Return Values
[in] alert (referenced PBAlert):
[in] newMessage (nullable referenced PBTextDocument):
PBAlertSetDescription
Function:
Syntax (C/C++)
void PBAlertSetDescription(PBAlertRef alert,
PBTextDocumentRef _Nullable newDescription);
Syntax (Python)
AlertSetDescription(alert, newDescription)
Parameters and Return Values
[in] alert (referenced PBAlert):
[in] newDescription (nullable referenced PBTextDocument):
PBAlertGetButtonArea
Function:
Syntax (C/C++)
PBElementPtr _Nullable PBAlertGetButtonArea(PBAlertRef alert);
Syntax (Python)
AlertGetButtonArea(alert) -> (buttonArea)
Parameters and Return Values
[in] alert (referenced PBAlert):
[out] buttonArea (nullable owned PBElement):
PBAlertAddSimpleError
Function: Show a simple error message in an alert.
Syntax (C/C++)
void PBAlertAddSimpleError(PBWindowRef _Nullable owner, ConstStr message,
ConstStr description);
Syntax (Python)
AlertAddSimpleError(owner, message, description)
Parameters and Return Values
[in] owner (nullable referenced PBWindow): The owner window to which to attach the alert; or null to leave it unattached.
[in] message (referenced string): The error message itself.
[in] description (referenced string): An extended description of the error.
Discussion
This function returns immediately; it does not wait for the user to close the alert.
The alert will display the error message and description (if provided), as well as a single button to dismiss the alert.
If an owner window is given, then the user will not be able to interact with that window through the keyboard or mouse until the alert error is dismissed.
Example (C/C++)
PBAlertAddSimpleError(window, PB_STR("The folder is inaccessible."),
PB_STR("You may not have permission to open it."));