SystemListDialog

#include <bb/system/SystemListDialog>

To link against this class, add the following line to your .pro file: LIBS += -lbbsystem

A dialog box that presents the user with a list of choices.

The dialog box displayed will be an application-modal window, though it is possible to use a system-modal window by setting the SystemListDialog::modality property. The dialog box presents a list of choices. By default, single selection mode is enabled, which allows a user to select a single option from the list. Alternately, multiple selection mode can be enabled to allow the user to select multiple options from the list. In both modes, the user can choose to select none of the presented options.

In addition, the buttonAreaLimit property controls the number of buttons that will be contained in the button area of the window. By default, the button area will be large enough to contain confirmButton, customButton, and cancelButton, if they are valid. The buttons will be considered invalid if they do not have a label set.

Presentation properties are marked as such, and affect future requests. Any pending requests will use the values of the presentation properties at the time of the request.

Note:

To update a dialog box, call exec() or show() after setting new values for presentation properties.

Since:

BlackBerry 10.0.0

Public Functions Index

SystemListDialog (QObject *parent=0)
SystemListDialog (const QString &confirmLabel, QObject *parent=0)
SystemListDialog (const QString &confirmLabel, const QString &cancelLabel, QObject *parent=0)
SystemListDialog (const QString &confirmLabel, const QString &customLabel, const QString &cancelLabel, QObject *parent=0)
virtual ~SystemListDialog ()
bb::system::ListSelectionMode::TypeselectionMode () const
QStringtitle () const
QStringbody () const
boolemoticonsEnabled () const
boolincludeRememberMe () const
boolrememberMeChecked () const
QStringrememberMeText () const
SystemUiButton *confirmButton ()
SystemUiButton *customButton ()
SystemUiButton *cancelButton ()
SystemUiButton *defaultButton ()
booldismissAutomatically () const
bb::system::SystemUiReturnKeyAction::TypereturnKeyAction () const
bb::system::SystemUiModality::Typemodality () const
intbuttonAreaLimit () const
voidsetSelectionMode (bb::system::ListSelectionMode::Type selectionMode)
voidsetTitle (const QString &title)
voidsetBody (const QString &body)
voidsetEmoticonsEnabled (bool newEmoticonsEnabled)
voidsetIncludeRememberMe (bool value)
voidsetRememberMeChecked (bool newRememberMeSelected)
voidsetRememberMeText (const QString &newRememberMeText)
voidsetDefaultButton (bb::system::SystemUiButton *newDefaultButton)
voidsetDismissAutomatically (bool automaticDismissal)
voidsetReturnKeyAction (bb::system::SystemUiReturnKeyAction::Type newReturnKeyAction)
voidsetModality (bb::system::SystemUiModality::Type newModality)
voidsetButtonAreaLimit (int newButtonAreaLimit)
Q_INVOKABLE voidresetSelectionMode ()
Q_INVOKABLE voidresetTitle ()
Q_INVOKABLE voidresetBody ()
Q_INVOKABLE voidresetEmoticonsEnabled ()
Q_INVOKABLE voidresetIncludeRememberMe ()
Q_INVOKABLE voidresetRememberMeChecked ()
Q_INVOKABLE voidresetRememberMeText ()
Q_INVOKABLE voidresetConfirmButton ()
Q_INVOKABLE voidresetCustomButton ()
Q_INVOKABLE voidresetCancelButton ()
Q_INVOKABLE voidresetDefaultButton ()
Q_INVOKABLE voidresetDismissAutomatically ()
Q_INVOKABLE voidresetReturnKeyAction ()
Q_INVOKABLE voidresetModality ()
Q_INVOKABLE voidresetButtonAreaLimit ()
voidappendButton (SystemUiButton *button)
Q_INVOKABLE intbuttonCount () const
SystemUiButton *buttonAt (int index) const
Q_INVOKABLE voidclearButtons ()
bb::system::SystemUiResult::Typeresult () const
bb::system::SystemUiError::Typeerror () const
Q_INVOKABLE bb::system::SystemUiButton *buttonSelection () const
Q_INVOKABLE boolrememberMeSelection () const
QList< int >selectedIndices () const
Q_INVOKABLE voidappendSeparator (const QString &text)
Q_INVOKABLE voidappendHeader (const QString &text)
Q_INVOKABLE voidappendHeader (const QString &text, bool enabled)
Q_INVOKABLE voidappendItem (const QString &text)
Q_INVOKABLE voidappendItem (const QString &text, bool enabled)
Q_INVOKABLE voidappendItem (const QString &text, bool enabled, bool selected)
Q_INVOKABLE voidappendItems (const QList< QString > &text)

Public Slots Index

voidclearList ()
voidshow ()
bb::system::SystemUiResult::Typeexec ()
voidcancel ()

Signals Index

voidfinished (bb::system::SystemUiResult::Type value)
voidselectionModeChanged (bb::system::ListSelectionMode::Type newSelectionMode)
voidtitleChanged (const QString &value)
voidbodyChanged (const QString &value)
voidemoticonsEnabledChanged (bool newEmoticonsEnabled)
voidincludeRememberMeChanged (bool value)
voidrememberMeCheckedChanged (bool newRememberMeSelected)
voidrememberMeTextChanged (const QString &newRememberMeText)
voiddefaultButtonChanged (bb::system::SystemUiButton *newDefaultButton)
voiddismissAutomaticallyChanged (bool automaticDismissal)
voidreturnKeyActionChanged (bb::system::SystemUiReturnKeyAction::Type newReturnKeyAction)
voidmodalityChanged (bb::system::SystemUiModality::Type newModality)
voidbuttonAreaLimitChanged (int newButtonAreaLimit)

Properties

QString title

Represents the title of the window.

This is a presentation property whose default value is a default-constructed QString.

Since:

BlackBerry 10.0.0

QString body

Represents the main text of the window.

This is a presentation property whose default value is a default-constructed QString.

Since:

BlackBerry 10.1.0

bool emoticonsEnabled

Retrieves whether the text can be displayed with emoticons.

This is a presentation property whose default value is false.

Since:

BlackBerry 10.1.0

bool includeRememberMe

Indicates whether a toggle switch for remembering user selection should be included in the dialog box.

If a toggle switch is requested, then the user will have the ability to enable and disable it. The user selection will be available using rememberMeSelection() when the request is finished. To customize how the toggle switch is presented, use rememberMeChecked() and rememberMeText().

This is a presentation property whose default value is false.

Since:

BlackBerry 10.1.0

bool rememberMeChecked

Represents the checked state of the toggle switch for remembering user selection.

The state is only applied if includeRememberMe is true. To obtain the user selection for this property once the request is finished, use rememberMeSelection().

This is a presentation property whose default value is true.

Since:

BlackBerry 10.1.0

QString rememberMeText

Represents the text to associate with the toggle switch associated with rememberMeChecked.

This property is only applied if includeRememberMe is true.

This is a presentation property whose default value is "Remember Me".

Since:

BlackBerry 10.1.0

int buttonAreaLimit

The maximum number of buttons that can be shown without causing an overflow.

When overflow occurs all buttons will be stacked vertically.

This is a presentation property whose default value is -1.
Note:

-1 implies that default system behavior will be applied. The supported range is 1-3, with any values outside the range resetting the property to its default value.

Since:

BlackBerry 10.0.0

bool dismissAutomatically

Indicates whether to dismiss the dialog box when a button is selected.

If false, the dialog box must be dismissed using cancel(). Otherwise, the dialog box is dismissed with a button selection.

This is a presentation property whose default value is true.

Since:

BlackBerry 10.0.0

bb::system::SystemUiReturnKeyAction::Type returnKeyAction

Represents the action associated with the return key for this dialog box.

This a presentation property whose default value is bb::system::SystemUiReturnKeyAction::Default.
See:

bb::system::SystemUiReturnKeyAction for the list of possible values.

Since:

BlackBerry 10.0.0

bb::system::SystemUiModality::Type modality

Represents the modality of the dialog box.

This is a presentation property whose value is bb::system::SystemUiModality::Application.
See:

bb::system::SystemUiModality for the list of valid values.

Since:

BlackBerry 10.0.0

bb::system::ListSelectionMode::Type selectionMode

Controls the number of items that may be selected in the list for this dialog box.

If this property is set to ListSelectionMode::Single, selecting one item in the list will clear any other item in the list. If it is set to bb::system::ListSelectionMode::Multiple, then any number of items may be selected in the list. In either selection mode, the user can decide to select no items from the list.

This is a presentation property whose default value is bb::system::ListSelectionMode::Single.
See:

bb::system::ListSelectionMode for the list of valid values.

Since:

BlackBerry 10.0.0

bb::system::SystemUiButton confirmButton[read-only]

Represents the button associated with the default confirming action of the window.

This is a presentation property whose default bb::system::SystemUiButton::label property is "OK".

Note:

This button is omitted if its bb::system::SystemUiButton::label property is a default-constructed QString.

Since:

BlackBerry 10.0.0

bb::system::SystemUiButton customButton[read-only]

Represents the button associated with the tertiary action of the window.

This is a presentation property whose default bb::system::SystemUiButton::label property is a default-constructed QString.

Note:

This button is omitted if its bb::system::SystemUiButton::label property is a default-constructed QString.

Since:

BlackBerry 10.0.0

bb::system::SystemUiButton cancelButton[read-only]

Represents the button associated with the default cancellation action of the window.

This is a presentation property whose default bb::system::SystemUiButton::label property is "Cancel".

Note:

This button is omitted if its bb::system::SystemUiButton::label property is a default-constructed QString.

Since:

BlackBerry 10.0.0

bb::system::SystemUiButton defaultButton

Represents the button associated with the return key action of the window.

When the user triggers the return key action, this button will be automatically selected. If the defaultButton is NULL, then triggering the return key action will not select any button.

If defaultButton is set to a button that this instance does not manage, then this property is undefined.

This is a presentation property whose default value determined dynamically based on which managed buttons are available. The precedence of the buttons is as follows:

  • confirmButton

  • cancelButton

  • customButton

  • last element of buttons

Since:

BlackBerry 10.0.0

QDeclarativeListProperty< bb::system::SystemUiButton > buttons[read-only]

Represents any additional buttons to include in the window.

This is a presentation property which is initialized as an empty list.

Since:

BlackBerry 10.0.0

bb::system::SystemUiResult::Type result[read-only]

Represents the result of the last completed request.

To obtain result values once the request is finished, use the following functions:
See:

bb::system::SystemUiResult for the list of possible results.

Since:

BlackBerry 10.0.0

bb::system::SystemUiError::Type error[read-only]

Represents the last error encountered.

This property is only valid when the SystemListDialog::result property is bb::system::SystemUiResult::Error.
See:

bb::system::SystemUiError for the list of possible errors.

Since:

BlackBerry 10.0.0

QVariantList selectedIndices[read-only]

The selected elements in the supplied list of elements.

This list contains the indices of the elements that were selected in the list. If this dialog box is set to bb::system::ListSelectionMode::Single (the default) the list will either be empty or contain exactly one value. If the dialog box is set to bb::system::ListSelectionMode::Multiple then the list will contain zero or more indices.

Note:

The indices are the position of the elements as they were appended to the dialog box, not the index of the selectable items within the list. For example, if you appended a header, then a separator, followed by 2 items, and the user selected the first item in the list the value 2 will be returned (the header is at index 0, the separator is at index 1, and the items are at indices 2 and 3 respectively).

Since:

BlackBerry 10.0.0

Public Functions

SystemListDialog (

The default property is buttons.

Constructs a new instance of a dialog box with default confirmation and cancellation buttons.

The confirmation and cancellation buttons will have their default label values.
Parameters
parent

If not 0, the supplied parent will be responsible for deleting this instance.
Since:

BlackBerry 10.0.0

SystemListDialog (

Constructs a new instance of a dialog box with only a confirmation button.

To show the cancellation and custom button set the labels of SystemListDialog::cancelButton and SystemListDialog::customButton respectively.
Parameters
confirmLabel

The label to use for the confirmation button.

parent

If not 0, the supplied parent will be responsible for deleting this instance.
Since:

BlackBerry 10.0.0

SystemListDialog (

Constructs a new instance of a dialog box with defined confirmation and cancellation buttons.

To show the custom button set the label of SystemListDialog::customButton.
Parameters
confirmLabel

The label to use for the confirmation button.

cancelLabel

The label to use for the cancellation button.

parent

If not 0, the supplied parent will be responsible for deleting this instance.
Since:

BlackBerry 10.0.0

SystemListDialog (

Constructs a new instance of a dialog box with defined confirmation, custom, and cancellations buttons.

Parameters
confirmLabel

The label to use for the confirmation button.

customLabel

The label to use for the custom button.

cancelLabel

The label to use for the cancellation button.

parent

If not 0, the supplied parent will be responsible for deleting this instance.
Since:

BlackBerry 10.0.0

virtual~SystemListDialog ()

Destructor.

Since:

BlackBerry 10.0.0

bb::system::ListSelectionMode::Type selectionMode ()

Obtains the current selection mode for the dialog box.

Return:

The current selection mode of the dialog box. See bb::system::ListSelectionMode for the list of selection modes.

Since:

BlackBerry 10.0.0

QString title ()

Retrieves the title for the dialog box.

Return:

The title of the dialog box.

Since:

BlackBerry 10.0.0

QString body ()

Retrieves the main text of the dialog box.

Return:

The text of the dialog box.

Since:

BlackBerry 10.1.0

bool emoticonsEnabled ()

Retrieves whether the text can be displayed as emoticons.

Return:

Whether the dialog box supports emoticons.

Since:

BlackBerry 10.1.0

bool includeRememberMe ()

Retrieves the flag indicating if a toggle switch to remember user selection should be included in the dialog box.

Return:

true if a toggle for remembering the user selection should be included in the dialog box, false otherwise.

Since:

BlackBerry 10.1.0

bool rememberMeChecked ()

Retrieves whether the toggle switch for includeRememberMe will be selected by default.

To obtain the user selection, use rememberMeSelection() instead.
Return:

true if the toggle should be selected by default, false otherwise.

Since:

BlackBerry 10.1.0

QString rememberMeText ()

Retrieves the text associated with the toggle switch for includeRememberMe.

Return:

The text for the toggle for includeRememberMe.

Since:

BlackBerry 10.1.0

SystemUiButton * confirmButton ()

Retrieves the dialog box's confirmation button.

This instance retains ownership of the returned value.
Return:

The dialog box's confirmation button.

Since:

BlackBerry 10.0.0

SystemUiButton * customButton ()

Retrieves the dialog box's custom action button.

This instance retains ownership of the returned value.
Return:

The dialog box's custom action button.

Since:

BlackBerry 10.0.0

SystemUiButton * cancelButton ()

Retrieves the dialog box's cancellation button.

This instance retains ownership of the returned value.
Return:

The dialog box's cancellation button.

Since:

BlackBerry 10.0.0

SystemUiButton * defaultButton ()

Retrieves the dialog box's default button.

This instance retains ownership of the returned value.

The default button is automatically selected when the user triggers the return key action. If the default button is NULL, no button will be automatically selected.

The returned value will be one of the buttons managed by this instance, or NULL.
Return:

The dialog box's default button.

Since:

BlackBerry 10.0.0

bool dismissAutomatically ()

Indicates if the dialog box is dismissed when a button is selected.

Return:

true if selecting a button dismisses the dialog box, false otherwise.

Since:

BlackBerry 10.0.0

bb::system::SystemUiReturnKeyAction::Type returnKeyAction ()

Retrieves the dialog box's return key action.

Return:

The dialog box's return key action.

Since:

BlackBerry 10.0.0

bb::system::SystemUiModality::Type modality ()

Retrieves the dialog box's modality.

Return:

The dialog box's modality. See bb::system::SystemUiModality for the list of possible values.

Since:

BlackBerry 10.0.0

int buttonAreaLimit ()

The maximum number of buttons that can be shown without causing an overflow.

If buttonAreaLimit is larger than the number of buttons that will be displayed, all buttons will be stacked vertically.
Return:

The limit for the number of buttons that can be accommodated in the button area, or -1 if system defaults should be used.

Since:

BlackBerry 10.0.0

void setSelectionMode (

Changes the way in which selection works for this dialog box.

Parameters
selectionMode

The new method by which selections can be made in the list. See bb::system::ListSelectionMode for the list of selection modes.
Since:

BlackBerry 10.0.0

void setTitle (

Sets the title for the dialog box.

Parameters
title

The new title of the dialog box.
Since:

BlackBerry 10.0.0

void setBody (

Sets the main text of the dialog box.

Parameters
body

The new text of the dialog box.
Since:

BlackBerry 10.1.0

void setEmoticonsEnabled (
  • boolnewEmoticonsEnabled)

Sets whether the text can be displayed as emoticons.

Parameters
newEmoticonsEnabled

Whether the dialog box supports emoticons.
Since:

BlackBerry 10.1.0

void setIncludeRememberMe (
  • boolvalue)

Sets the flag indicating if a toggle switch for remembering user selection should be included in the dialog box.

Parameters
value

true if a toggle for remembering user selection should be included, false otherwise.
Since:

BlackBerry 10.1.0

void setRememberMeChecked (
  • boolnewRememberMeSelected)

Sets whether the toggle switch for includeRememberMe will be selected by default.

Parameters
newRememberMeSelected

true if the toggle should be selected by default, false otherwise.
Since:

BlackBerry 10.1.0

void setRememberMeText (

Sets the text associated with the the toggle switch for includeRememberMe.

Parameters
newRememberMeText

The new text for the toggle for includeRememberMe.
Since:

BlackBerry 10.1.0

void setDefaultButton (

Sets the dialog box's default button.

newDefaultButton must be one of the buttons managed by this instance, or NULL. If NULL is specified, then no button will be associated with the return key action.

If a non-managed button is specified, then this property is undefined.
Parameters
newDefaultButton

The button to associate with the return key action.
Since:

BlackBerry 10.0.0

void setDismissAutomatically (
  • boolautomaticDismissal)

Sets whether the dialog box is dismissed when a button is selected.

Parameters
automaticDismissal

true if the dialog box should be automatically dismissed on a button press, false otherwise.
Since:

BlackBerry 10.0.0

void setReturnKeyAction (

Sets the return key action for the dialog box.

Parameters
newReturnKeyAction

The new return key action.
Since:

BlackBerry 10.0.0

void setModality (

Sets the modality for the dialog box.

Parameters
newModality

The new modality preference.

See:

bb::system::SystemUiModality for the list of possible values.

Since:

BlackBerry 10.0.0

void setButtonAreaLimit (
  • intnewButtonAreaLimit)

Sets the maximum number of buttons to accommodate in the dialog box button area without overflow.

Values outside the range [1,3] will reset the property to its default value, -1. If newButtonAreaLimit is smaller than the number of buttons that will be displayed, all buttons will be stacked vertically.
Parameters
newButtonAreaLimit

The maximum number of buttons in the button area.
Since:

BlackBerry 10.0.0

Q_INVOKABLE void resetSelectionMode ()

Returns the selection mode to the default of bb::system::ListSelectionMode::Single.

Since:

BlackBerry 10.0.0

Q_INVOKABLE void resetTitle ()

Resets the title of the dialog box to QString::null.

Since:

BlackBerry 10.0.0

Q_INVOKABLE void resetBody ()

Resets the main text of the dialog box to QString::null.

Since:

BlackBerry 10.1.0

Q_INVOKABLE void resetEmoticonsEnabled ()

Resets whether the text can display emoticons to false.

Since:

BlackBerry 10.1.0

Q_INVOKABLE void resetIncludeRememberMe ()

Resets the flag to show the toggle for remembering user selection to false.

To reset the selection state for the toggle, use resetRememberMeChecked().

Since:

BlackBerry 10.1.0

Q_INVOKABLE void resetRememberMeChecked ()

Resets the selection state for the toggle switch for includeRememberMe to true.

To reset whether to include the toggle switch use resetIncludeRememberMe().

Since:

BlackBerry 10.1.0

Q_INVOKABLE void resetRememberMeText ()

Resets the text for the toggle switch for includeRememberMe to "Remember Me".

Since:

BlackBerry 10.1.0

Q_INVOKABLE void resetConfirmButton ()

Resets the confirmation button for this dialog box.

When the confirmation button is reset, its label will be set to the default value of "OK".

Since:

BlackBerry 10.0.0

Q_INVOKABLE void resetCustomButton ()

Resets the custom action button for this dialog box.

When the custom action button is reset, its label will be an empty QString so this button will be omitted during show() and exec() events.

Since:

BlackBerry 10.0.0

Q_INVOKABLE void resetCancelButton ()

Resets the cancellation button for this dialog box.

When the cancellation button is reset, its label will be set to the default value of "Cancel".

Since:

BlackBerry 10.0.0

Q_INVOKABLE void resetDefaultButton ()

Resets the default button for this dialog box based on the property's precedence rules.

Since:

BlackBerry 10.0.0

Q_INVOKABLE void resetDismissAutomatically ()

Resets whether the dialog box is dismissed when a button is selected to true.

Since:

BlackBerry 10.0.0

Q_INVOKABLE void resetReturnKeyAction ()

Resets the return key action of the dialog box to bb::system::SystemUiReturnKeyAction::Default.

Since:

BlackBerry 10.0.0

Q_INVOKABLE void resetModality ()

Resets the modality of the dialog box to bb::system::SystemUiModality::Application.

Since:

BlackBerry 10.0.0

Q_INVOKABLE void resetButtonAreaLimit ()

Resets the maximum number of buttons to accommodate in the dialog box button area without overflow to -1.

Since:

BlackBerry 10.0.0

void appendButton (

Appends a button to the list of other buttons for this dialog box.

The dialog box will become the parent of the button and be responsible for destroying it.
Parameters
button

The button to add to this dialog box.
Since:

BlackBerry 10.0.0

Q_INVOKABLE int buttonCount ()

Retrieves the number of other buttons added to the dialog box.

This method returns the count of buttons added using the appendButton() method. The count does not include the confirmation, custom, or cancellation buttons.
Return:

Returns the number of other buttons.

Since:

BlackBerry 10.0.0

SystemUiButton * buttonAt (
  • intindex)

Retrieves the button at the supplied index.

This instance retains ownership of the returned value.
Parameters
index

An index into the list of buttons added using the appendButton() method.

Return:

Returns the button at the supplied index or 0 if an invalid index is provided.

Since:

BlackBerry 10.0.0

Q_INVOKABLE void clearButtons ()

Clears the list of other buttons for this dialog box.

This method only affects buttons added to the dialog box using the appendButton() method. This method does not affect the confirmation, custom, or cancellation buttons. The button instances will be deleted.

Since:

BlackBerry 10.0.0

bb::system::SystemUiResult::Type result ()

Retrieves the result of the last completed request.

If no request has been made, or if a request is pending, bb::system::SystemUiResult::None is returned.
Return:

The result of the last completed request. See bb::system::SystemUiResult for the list of possible results.

Since:

BlackBerry 10.0.0

bb::system::SystemUiError::Type error ()

Retrieves the error that occurred during the request.

The return value will be reset when a new request is made.
Return:

The error that occurred. See bb::system::SystemUiError for the list of possible errors.

Since:

BlackBerry 10.0.0

Q_INVOKABLE bb::system::SystemUiButton * buttonSelection ()

Returns the button that was selected when a button selection is made.

If no button was selected, 0 will be returned.

This function will return the result of the button selection of show() and exec().

The return value will be reset when a new request is made.

This instance retains ownership of the returned value.
Return:

The button selected by the user.

Since:

BlackBerry 10.0.0

Q_INVOKABLE bool rememberMeSelection ()

Returns the state of the toggle for remembering user selection when the user dismisses the dialog box.

Return:

true if the toggle for remembering the user selection was checked, false otherwise.

Since:

BlackBerry 10.1.0

QList< int > selectedIndices ()

Returns the indices of the selected elements in this dialog box when a button is pressed.

This list contains the indices of the elements that were selected in the list when a button is pressed. If the selection mode is set to bb::system::ListSelectionMode::Single (the default) the list will either be empty or contain exactly one value. If the selection mode is set to bb::system::ListSelectionMode::Multiple the list will contain zero or more values.

Note:

The indices are the position of the elements as they were appended to the dialog box, not the index of the selectable items within the list. For example, if you appended a header, then a separator, followed by 2 items, and the user selected the first Item in the list the value 2 will be returned (the header is 0, the separator is 1, and the items are 2 and 3 respectively).

Return:

The list of selected element indices from the dialog box.

Since:

BlackBerry 10.0.0

Q_INVOKABLE void appendSeparator (

Adds a non-selectable separator to the list to be presented.

Parameters
text

The string to be displayed as the separator.
Since:

BlackBerry 10.0.0

Q_INVOKABLE void appendHeader (

Adds a non-selectable header to the list to be presented.

Parameters
text

The string to be displayed as the header.
Since:

BlackBerry 10.0.0

Q_INVOKABLE void appendHeader (

Adds a non-selectable, optionally disabled, header to the list to be presented.

Parameters
text

The string to be display as the header.

enabled

If false, the header will be visually disabled.
Since:

BlackBerry 10.0.0

Q_INVOKABLE void appendItem (

Adds a selectable item to the list to be presented.

Parameters
text

The string to be displayed for this selectable item.
Note:

The item is not tracked by this dialog box or retrievable from this dialog box, so in order to correlate a SystemListDialog::selectedIndices entry to an item you will be required to maintain this information yourself.

Since:

BlackBerry 10.0.0

Q_INVOKABLE void appendItem (

Adds a selectable, optionally disabled, item to the list to be presented.

Parameters
text

The string to be displayed for this selectable item.

enabled

If set to false this item will be visually disabled and will not be allowed to have its selected state toggled.
Note:

The item is not tracked by this dialog box or retrievable from this dialog box, so in order to correlate a SystemListDialog::selectedIndices entry to an item you will be required to maintain this information yourself.

Since:

BlackBerry 10.0.0

Q_INVOKABLE void appendItem (
  • const QString &text,
  • boolenabled,
  • boolselected )

Adds a selectable, optionally disabled and selected, item to the list to be presented.

Parameters
text

The string to be displayed for this selectable item.

enabled

If set to false this item will be visually disabled and will not be allowed to have its selected state toggled.

selected

If set to true, this item will be initially displayed as already selected, if the selection mode allows it.
Note:

The item is not tracked by this dialog box or retrievable from this dialog box, so in order to correlate a SystemListDialog::selectedIndices entry to an item you will be required to maintain this information yourself.

Since:

BlackBerry 10.0.0

Q_INVOKABLE void appendItems (

Adds a collection of items to the list, each of which will be enabled and cleared.

Parameters
text

The list of strings to be added to the list.
Note:

The item is not tracked by this dialog box or retrievable from this dialog box, so in order to correlate a SystemListDialog::selectedIndices entry to an item you will be required to maintain this information yourself.

Since:

BlackBerry 10.0.0

Public Slots

void clearList ()

Removes all headers, separators and items from the list to be presented.

Since:

BlackBerry 10.0.0

void show ()

Displays or updates the dialog box based on current property values.

The result of the request can be retrieved with the SystemListDialog::result property, or using the signal finished(). The button selection can be retrieved with the SystemListDialog::buttonSelection property. The list of selected item indices can be retrieved with the SystemListDialog::selectedIndices property.

Control is returned to the caller immediately. For a blocking request, use exec().

Since:

BlackBerry 10.0.0

bb::system::SystemUiResult::Type exec ()

Displays the dialog box based on current property values.

The result of the request can be retrieved with the SystemListDialog::result property, or using the signal finished(). The button selection can be retrieved with the SystemListDialog::buttonSelection property. The list of selected item indices can be retrieved with the SystemListDialog::selectedIndices property.

Unlike show(), this function will block until a button selection is made.

Note:
Blocking occurs by starting a nested QEventLoop. To use this method safely, the following conditions must be met:

  • Any connections to this slot must use a Qt::QueuedConnection, or the slot must be triggered using QTimer::singleShot(), and

  • QObject::deleteLater() must be used in place of delete when deleting the dialog box object. If these conditions are not met, unexpected behavior may result.

Return:

The result of the request. See bb::system::SystemUiResult for the list of possible results.

Since:

BlackBerry 10.0.0

void cancel ()

Cancels the dialog box if it is still displayed.

Since:

BlackBerry 10.0.0

Signals

void finished (

Emitted when a request is completed.

The button selection can be retrieved with buttonSelection(). The list of selected item indices can be retrieved with the selectedIndices property. The state of the toggle for remembering the content of this dialog box can be retrieved using rememberMeSelection().
Parameters
value

The result of the request. See bb::system::SystemUiResult for the list of possible results.
Since:

BlackBerry 10.0.0

void selectionModeChanged (

Emitted when the selectionMode property is changed programmatically.

Parameters
newSelectionMode

The new selection mode for this dialog box. See bb::system::ListSelectionMode for the list of possible selection modes.
Since:

BlackBerry 10.0.0

void titleChanged (

Emitted when the title property is changed programmatically.

Parameters
value

The new value of the title property.
Since:

BlackBerry 10.0.0

void bodyChanged (

Emitted when the body property is changed programmatically.

Parameters
value

The new value of the body property.
Since:

BlackBerry 10.1.0

void emoticonsEnabledChanged (
  • boolnewEmoticonsEnabled)

Emitted when the emoticonsEnabled property is changed programmatically.

Parameters
newEmoticonsEnabled

The new value of the emoticonsEnabled property.
Since:

BlackBerry 10.1.0

void includeRememberMeChanged (
  • boolvalue)

Emitted when the includeRememberMe property is changed programmatically.

Parameters
value

The new value of the includeRememberMe property.
Since:

BlackBerry 10.1.0

void rememberMeCheckedChanged (
  • boolnewRememberMeSelected)

Emitted when the rememberMeChecked property is changed programmatically.

When the user dismisses the dialog box, the user selection is available using rememberMeSelection().
Parameters
newRememberMeSelected

The new value of the rememberMeChecked property.
Since:

BlackBerry 10.1.0

void rememberMeTextChanged (

Emitted when the rememberMeText property is changed programmatically.

Parameters
value

The new value of the rememberMeText property.
Since:

BlackBerry 10.1.0

void defaultButtonChanged (

Emitted when the defaultButton property is changed programmatically.

Parameters
newDefaultButton

The new value of the defaultButton property, or NULL if none is set.
Since:

BlackBerry 10.0.0

void dismissAutomaticallyChanged (
  • boolautomaticDismissal)

Emitted when the dismissAutomatically property is changed programmatically.

Parameters
automaticDismissal

The new value of the dismissAutomatically property.
Since:

BlackBerry 10.0.0

void returnKeyActionChanged (

Emitted when the returnKeyAction property is changed programmatically.

Parameters
newReturnKeyAction

The new value of the returnKeyAction property.
Since:

BlackBerry 10.0.0

void modalityChanged (

Emitted when the modality property is changed programmatically.

Parameters
newModality

The new value of the modality property.
Since:

BlackBerry 10.0.0

void buttonAreaLimitChanged (
  • intnewButtonAreaLimit)

Emitted when the buttonAreaLimit property is changed programmatically.

Parameters
newButtonAreaLimit

The new value of the buttonAreaLimit property.
Since:

BlackBerry 10.0.0