TitleBar

Since: BlackBerry 10.0.0

#include <bb/cascades/TitleBar>

Defines a title bar on a page.

The title bar consists of a title with optional actions for accepting or declining an action, or an optional set of selectable options, depending on the type of title bar. You can define the type of title bar to display using the kind property. Possible values are Default (allows the action buttons to be displayed), Segmented (allows a SegmentedControl to be displayed), and FreeForm (allows controls to be placed freely on the title bar). The actions will be displayed on the title bar, which is placed at the top of the screen.

Here's an example of a default title bar:

QML:

 Page {
     titleBar: TitleBar {
         title : "This is a page title"
     }
 }

C++:

 TitleBar* tb = new TitleBar();
 tb->setTitle("This is a page title");
 Page* page = Page::create().titleBar(tb);

Here's a title bar containing options:

 Page {
     titleBar: TitleBar {
         kind: TitleBarKind.Segmented
         options: [
             Option {
                 text: "Todo"
                 value: "todo"
             },
             Option {
                 text: "Finished"
                 value: "finished"
             },
             Option {
                 text: "Chickened out"
                 value: "chickened"
             }
         ]
     }
 }

And lastly, this is a free-form title bar containing expandable content:

 Page {
     titleBar: TitleBar {
         kind: TitleBarKind.FreeForm
         kindProperties: FreeFormTitleBarKindProperties {
             Container {
                 layout: StackLayout { orientation: LayoutOrientation.LeftToRight }
                 leftPadding: 10
                 rightPadding: 10
                 Label {
                     text: "Show expandable content"
                     textStyle {
                         color: Color.White
                     }
                     verticalAlignment: VerticalAlignment.Center
                     layoutProperties: StackLayoutProperties { spaceQuota: 1 }
                 }
                 CheckBox {
                     id: toggleExpanded
                     verticalAlignment: VerticalAlignment.Center
                 }
             }
             expandableArea {
                 content: RadioGroup {
                     Option { id: option1; text: "option 1"; selected: true }
                     Option { id: option2; text: "option 2" }
                     Option { id: option3; text: "option 3" }
                 }
                 indicatorVisibility: TitleBarExpandableAreaIndicatorVisibility.Hidden
                 expanded: toggleExpanded.checked
                 onExpandedChanged: {
                     toggleExpanded.checked = expanded
                 }
             }
         }
     }
 }

Overview

Inheritance

bb::cascades::BaseObject
	bb::cascades::UIObject
		bb::cascades::TitleBar

QML properties

acceptAction	: bb::cascades::ActionItem
appearance	: bb::cascades::TitleBarAppearance::Type
options	: QDeclarativeListProperty [read-only]
branded	: bb::cascades::TriBool::Type
dismissAction	: bb::cascades::ActionItem
kind	: bb::cascades::TitleBarKind::Type
kindProperties	: bb::cascades::AbstractTitleBarKindProperties
scrollBehavior	: bb::cascades::TitleBarScrollBehavior::Type
selectedIndex	: int
selectedOption	: bb::cascades::Option
selectedOptionSet	: bool [read-only]
selectedValue	: QVariant [read-only]
title	: QString
visibility	: bb::cascades::ChromeVisibility::Type
attachedObjects	: QDeclarativeListProperty< QObject > [read-only]
objectName	: QString
parent	: QObject [read-only]
ui	: bb::cascades::UIConfig [read-only]

QML signals

onAcceptActionChanged	: {}
onAppearanceChanged	: {}
onBrandedChanged	: {}
onDismissActionChanged	: {}
onKindPropertiesChanged	: {}
onOptionAdded	: {}
onOptionRemoved	: {}
onSelectedIndexChanged	: {}
onSelectedOptionChanged	: {}
onSelectedOptionSetChanged	: {}
onSelectedValueChanged	: {}
onTitleChanged	: {}
onVisibilityChanged	: {}
onCreationCompleted	: {}
onObjectNameChanged	: {}

Properties Index

bb::cascades::ActionItem	acceptAction
bb::cascades::TitleBarAppearance::Type	appearance
QDeclarativeListProperty	options [read-only]
bb::cascades::TriBool::Type	branded
bb::cascades::ActionItem	dismissAction
bb::cascades::TitleBarKind::Type	kind
bb::cascades::AbstractTitleBarKindProperties	kindProperties
bb::cascades::TitleBarScrollBehavior::Type	scrollBehavior
int	selectedIndex
bb::cascades::Option	selectedOption
bool	selectedOptionSet [read-only]
QVariant	selectedValue [read-only]
QString	title
bb::cascades::ChromeVisibility::Type	visibility
QDeclarativeListProperty< QObject >	attachedObjects [read-only]
QString	objectName
QObject	parent [read-only]
bb::cascades::UIConfig	ui [read-only]

Public Static Attributes Index

const int

SelectedIndexNone

Public Functions Index

	TitleBar (TitleBarKind::Type kind=TitleBarKind::Default)
	TitleBar (TitleBarScrollBehavior::Type behavior, TitleBarKind::Type kind=TitleBarKind::Default)
virtual	~TitleBar ()
bb::cascades::ActionItem *	acceptAction () const
Q_INVOKABLE void	addOption (bb::cascades::Option *option)
bb::cascades::TitleBarAppearance::Type	appearance () const
bb::cascades::TriBool::Type	branded () const
bb::cascades::ActionItem *	dismissAction () const
Q_INVOKABLE int	indexOfOption (bb::cascades::Option *option) const
Q_INVOKABLE void	insertOption (int index, bb::cascades::Option *option)
bool	isSelectedOptionSet () const
bb::cascades::TitleBarKind::Type	kind () const
bb::cascades::AbstractTitleBarKindProperties *	kindProperties () const
Q_INVOKABLE bb::cascades::Option *	optionAt (int index) const
Q_INVOKABLE int	optionCount () const
Q_INVOKABLE void	removeAllOptions ()
Q_INVOKABLE bool	removeOption (bb::cascades::Option *option)
Q_SLOT void	resetAcceptAction ()
Q_SLOT void	resetAppearance ()
Q_SLOT void	resetBranded ()
Q_SLOT void	resetDismissAction ()
Q_SLOT void	resetKindProperties ()
Q_SLOT void	resetSelectedIndex ()
Q_SLOT void	resetSelectedOption ()
Q_SLOT void	resetTitle ()
Q_SLOT void	resetVisibility ()
bb::cascades::TitleBarScrollBehavior::Type	scrollBehavior () const
int	selectedIndex () const
bb::cascades::Option *	selectedOption () const
QVariant	selectedValue () const
Q_SLOT void	setAcceptAction (bb::cascades::ActionItem *acceptAction)
Q_SLOT void	setAppearance (bb::cascades::TitleBarAppearance::Type appearance)
Q_SLOT void	setBranded (bb::cascades::TriBool::Type branded)
Q_SLOT void	setDismissAction (bb::cascades::ActionItem *dismissAction)
Q_SLOT void	setKindProperties (bb::cascades::AbstractTitleBarKindProperties *kindProperties)
Q_SLOT void	setSelectedIndex (int index)
Q_SLOT void	setSelectedOption (bb::cascades::Option *option)
Q_SLOT void	setTitle (const QString &title)
Q_SLOT void	setVisibility (bb::cascades::ChromeVisibility::Type visibility)
QString	title () const
bb::cascades::ChromeVisibility::Type	visibility () const
virtual bool	event (QEvent *event)
void	setObjectName (const QString &name)
virtual Q_INVOKABLE QString	toDebugString () const
Q_INVOKABLE bb::cascades::UIConfig *	ui () const

Static Public Functions Index

Builder	create (TitleBarKind::Type kind=TitleBarKind::Default)
Builder	create (TitleBarScrollBehavior::Type behavior, TitleBarKind::Type kind=TitleBarKind::Default)

Protected Functions Index

Only has inherited protected functions

	BaseObject (QObject *parent=0)
virtual void	connectNotify (const char *signal)
virtual void	disconnectNotify (const char *signal)

Signals Index

void	acceptActionChanged (bb::cascades::ActionItem *acceptAction)
void	appearanceChanged (bb::cascades::TitleBarAppearance::Type newAppearance)
void	brandedChanged (bb::cascades::TriBool::Type newBrand)
void	dismissActionChanged (bb::cascades::ActionItem *dismissAction)
void	kindPropertiesChanged (bb::cascades::AbstractTitleBarKindProperties *kindProperties)
void	optionAdded (bb::cascades::Option *option)
void	optionRemoved (bb::cascades::Option *option)
void	selectedIndexChanged (int selectedIndex)
void	selectedOptionChanged (bb::cascades::Option *selectedOption)
void	selectedOptionSetChanged (bool selectedOptionSet)
void	selectedValueChanged (const QVariant &selectedValue)
void	titleChanged (const QString &title)
void	visibilityChanged (bb::cascades::ChromeVisibility::Type newVisibility)
void	creationCompleted ()
void	objectNameChanged (const QString &objectName)

Properties

bb::cascades::ActionItem acceptAction

An action that will be displayed beside the title in the TitleBar.

See also:

ActionItem

Since:

BlackBerry 10.0.0

bb::cascades::TitleBarAppearance::Type appearance

Specifies what appearance the TitleBar should have.

The default value is TitleBarAppearance::Type Default.

See also:

TitleBarAppearance

Since:

BlackBerry 10.0.0

Deprecated

BlackBerry 10.3.0 Do not use. This property has no impact on the TitleBar.

QDeclarativeListProperty options[read-only]

The list of Option controls in the TitleBar.

The list is empty initially if no options have been added.

Since:

BlackBerry 10.0.0

bb::cascades::TriBool::Type branded

Specifies whether the TitleBar should use the colors associated with the current visual brand.

Currently, the only available brand color is blue (the default). In the future, there may be the possibility to choose from different branding options.

When branded is set to True, the title bar assumes the color associated with the current brand. When set to False, the title bar keeps the default color associated with the application's VisualStyle (either Light or Dark).

If the VisualStyle is Light, the branded title bar is used by default. If the VisualStyle is Dark, the branded control is still available, but not used by default.

The default value is TriBool::Type Undefined.

Since:

BlackBerry 10.0.0

Deprecated

BlackBerry 10.3.0 Do not use. This property has no impact on the TitleBar.

bb::cascades::ActionItem dismissAction

An action that will be displayed beside the title in the TitleBar.

This action should typically be used to cancel an action or process, or to dismiss or close the current page.

See also:

AbstractActionItem

Since:

BlackBerry 10.0.0

bb::cascades::TitleBarKind::Type kind

The kind of TitleBar to create.

This property can only be set once during the construction of the TitleBar. Possible values for this property are Default, Segmented, and FreeForm.

The Default state displays the title bar with left-aligned title text that can be set using the title property. It is possible to add two action buttons to the Default title bar, one on either side of the title. If one or more action buttons are shown, the title text will be center-aligned.

If kind is set to Segmented, the title, acceptAction, and dismissAction properties are not used, and the title text will not be displayed. The title bar will instead display up to four options. These options can be set using the options property.

Since:

BlackBerry 10.0.0

bb::cascades::AbstractTitleBarKindProperties kindProperties

The properties associated with a certain title bar kind.

Depending on the kind that has been set on the TitleBar, a different set of properties are valid. These different sets properties are bundled in classes inheriting from AbstractTitleBarKindProperties.

Since:

BlackBerry 10.1.0

bb::cascades::TitleBarScrollBehavior::Type scrollBehavior

The title bar scroll behavior for the Page.

By default, the scrollBehavior of a Page is TitleBarScrollBehavior::Default.

Note:

The title bar can't be immersive (ChromeVisibility::Overlay) and have a non sticky scroll behavior (TitleBarScrollBehavior::NonSticky) at the same time. ScrollBehavior will have precedence over the immersive visibility.

Since:

BlackBerry 10.1.0

int selectedIndex

The index of the currently selected option.

The selectedIndexChanged() signal is emitted when the index of the selected option is changed.

The default selectedIndex is SelectedIndexNone, meaning that no option is selected.

Since:

BlackBerry 10.0.0

bb::cascades::Option selectedOption

The currently selected Option.

The selectedOptionChanged() signal is emitted when the selected option is changed.

The default selectedOption is 0, meaning that no option is selected.

Since:

BlackBerry 10.0.0

bool selectedOptionSet[read-only]

Indicates whether any option in the TitleBar is currently selected.

This property is set to true if any option is selected, and is set to false otherwise.

This property can be used to determine if any option is currently selected, in addition to examining the selectedIndex property (typically from QML). Specifically, if the hasSelectedOption property is false, the selectedIndex property will be set to SelectedIndexNone, which is not accessible from QML.

 TitleBar {
     onSelectedOptionSetChanged: {
         if (selectedOptionSet) {
             console.log("Selected option with index: " + selectedIndex);
         } else {
             console.log("No selected options");
         }
     }
 }

When the value of this property changes, the selectedOptionSetChange() signal is emitted.

Since:

BlackBerry 10.0.0

QVariant selectedValue[read-only]

The value of the currently selected Option.

The selectedValueChanged() signal is emitted when the selected option's value is changed.

The default selectedValue is an invalid QVariant if the selected option has no value set or no option is selected.

See also:

QVariant, QVariant::Invalid

Since:

BlackBerry 10.0.0

QString title

The title text to display on the TitleBar.

The default value is QString::Null, indicating that no title is set.

Since:

BlackBerry 10.0.0

bb::cascades::ChromeVisibility::Type visibility

The visibility mode of the TitleBar.

The default visibility state of a title bar is ChromeVisibility::Default.

Note:

Since:

BlackBerry 10.0.0

QDeclarativeListProperty< QObject > attachedObjects[read-only]

A hierarchical list of the UIObject's attached objects.

Since:

BlackBerry 10.0.0

QString objectName

This property is overridden from QObject.

See also:

QObject::objectName().

Since:

BlackBerry 10.0.0

QObject parent[read-only]

A read-only property that represents this object's parent.

The parent of an object is specified using QObject::setParent(QObject*). The purpose of the property is to expose the object's parent to QML.

This property is read-only to prevent modifications from QML, where typically the parent is declaratively set. In C++ code, the parent can be explicitly set using QObject::setParent(QObject*), or implicitly set by adding it to a visual container.

The default value of this property is 0.

Since:

BlackBerry 10.0.0

bb::cascades::UIConfig ui[read-only]

An object that gives access to unit conversion routines.

QML use:

        // Size using design units
        Container {
            preferredWidth: ui.du(12)
            preferredHeight: ui.du(5)
        }

        // Size using design units, snap to whole pixels
        Container {
            preferredWidth: ui.sdu(13.5)
            preferredHeight: ui.sdu(7.5)
        }

        // Size using absolute pixel values
        Container {
            preferredWidth: ui.px(150)
            preferredHeight: ui.px(50)
        }

C++ use:

Container *container1 = Container::create().background(Color::Red);
UIConfig *ui = container1->ui();
container1->setPreferredWidth(ui->du(12));
container1->setPreferredHeight(ui->du(5));

Container *container2 = Container::create().background(Color::Green);
container2->setPreferredWidth(ui->sdu(13.5));
container2->setPreferredHeight(ui->sdu(7.5));

Container *container3 = Container::create().background(Color::Blue);
container3->setPreferredWidth(ui->px(150));
container3->setPreferredHeight(ui->sdu(50));

Since:

Blackberry 10.3.0

Public Static Attributes

const int SelectedIndexNone ()

A constant indicating that there are no options selected.

Since:

BlackBerry 10.0.0

Public Functions

TitleBar (
TitleBarKind::Typekind)

Constructs a TitleBar of the specified kind.

The only way to set what kind of TitleBar to create is to pass the kind as a parameter to this constructor. See the documentation for the kind property for further information.

Parameters
kind	The kind of TitleBar to create, specified using the TitleBarKind::Type enumeration.

Since:

BlackBerry 10.0.0

TitleBar (
TitleBarScrollBehavior::Typebehavior,
TitleBarKind::Typekind )

Constructs a TitleBar of the specified kind and scroll behavior.

Parameters
behavior	The scroll behavior of TitleBar to create, specified using the TitleBarScrollBehavior::Type enumeration.
kind	The kind of TitleBar to create, specified using the TitleBarKind::Type enumeration.

Since:

BlackBerry 10.1.0

virtual~TitleBar ()

Destructor.

Since:

BlackBerry 10.0.0

bb::cascades::ActionItem * acceptAction ()

Returns the accept action for the TitleBar.

The TitleBar keeps the ownership of the accept action.

Return:

The accept action, or 0 if no accept action has been specified.

Since:

BlackBerry 10.0.0

Q_INVOKABLE void addOption (
bb::cascades::Option *option)

Adds an option to the TitleBar.

The added option is placed last in the TitleBar.

If the option has already been added to another control, it will be removed from that control and added to this TitleBar, which will also assume ownership of the Option. Once added, the optionAdded() signal is emitted.

If the option is 0, it is ignored.

If the Option is added at an index greater than 3, it is inserted as unselected.

If the option is added as a selected option, the selectedIndexChanged(), selectedOptionChanged(), and selectedValueChanged() signals are emitted.

Parameters
option	The Option to be added.

Since:

BlackBerry 10.0.0

bb::cascades::TitleBarAppearance::Type appearance ()

Returns the appearance of this TitleBar.

Return:

The appearance of this TitleBar.

Since:

BlackBerry 10.0.0

Deprecated

BlackBerry 10.3.0

bb::cascades::TriBool::Type branded ()

Returns the brand of this TitleBar.

Return:

The brand of this TitleBar.

Since:

BlackBerry 10.0.0

Deprecated

BlackBerry 10.3.0

bb::cascades::ActionItem * dismissAction ()

Returns the dismiss button for the TitleBar.

The TitleBar keeps the ownership of the dismiss action.

Return:

The dismiss action, or 0 if no dismiss action has been specified.

Since:

BlackBerry 10.0.0

Q_INVOKABLE int indexOfOption (
bb::cascades::Option *option)

Returns the index of a specific option.

If the option is 0 or the Option doesn't belong to the TitleBar, SelectedIndexNone is returned.

Parameters
option	The option to get the index of.

Return:

The index of the option, or SelectedIndexNone.

Since:

BlackBerry 10.0.0

Q_INVOKABLE void insertOption (
intindex,
bb::cascades::Option *option )

Inserts the Option at the specified index.

If the index is less than 0, the option is inserted at index 0. If the index is equal to or greater than count(), the option is appended last.

If the option is currently added to another control, it will be removed from that control and added to this TitleBar, which will also assume ownership of the option. Once added, the optionAdded() signal is emitted.

If the option is 0, it is ignored.

If the Option is added at an index greater than 3, it is inserted as unselected.

If the option is added as a selected option, the selectedIndexChanged(), selectedOptionChanged(), and selectedValueChanged() signals are emitted.

Parameters
index	The index to insert the Option at.
option	The Option to be inserted.

Since:

BlackBerry 10.0.0

bool isSelectedOptionSet ()

Returns whether the TitleBar has a selected option.

Return:

true if the TitleBar has a selected option, false otherwise.

Since:

BlackBerry 10.0.0

bb::cascades::TitleBarKind::Type kind ()

Returns the kind of the TitleBar.

See the documentation for the kind property for further information.

Return:

The kind of TitleBar, specified using the TitleBarKind::Type enumeration.

Since:

BlackBerry 10.0.0

bb::cascades::AbstractTitleBarKindProperties * kindProperties ()

Returns the kind properties of the TitleBar.

Return:

The kind properties of the TitleBar.

Since:

BlackBerry 10.1.0

Q_INVOKABLE bb::cascades::Option * optionAt (
intindex)

Returns an option at a specific index if the index is valid, 0 otherwise.

The ownership of the returned option is not changed; this TitleBar will still own the option.

Parameters
index	The index that specifies the option to return.

Return:

The requested option if index is valid, 0 otherwise.

Since:

BlackBerry 10.0.0

Q_INVOKABLE int optionCount ()

Returns the number of options in the TitleBar.

Return:

The number of options in the TitleBar.

Since:

BlackBerry 10.0.0

Q_INVOKABLE void removeAllOptions ()

Removes all options from the TitleBar and deletes them.

The optionRemoved() signal is emitted with the option parameter as 0.

The selectedIndexChanged(), selectedOptionChanged(), and selectedValueChanged() signals are emitted if an option was selected.

Since:

BlackBerry 10.0.0

Q_INVOKABLE bool removeOption (
bb::cascades::Option *option)

Removes the Option from the TitleBar.

This function removes the option from the TitleBar, if the option belonged to the TitleBar.

Once the Option is removed, the TitleBar no longer references it, but it is still owned by the Option. It is up to the application to either delete the removed Option, transfer its ownership (by setting its parent) to another object or leave it as a child of the TitleBar (in which case it will be deleted with the TitleBar).

If an Option before the selected option is removed, selectedIndexChanged() signal is emitted.

If the selected option is removed, the selectedIndex is set to 0 or SelectedIndexNone and the selectedIndexChanged(), selectedOptionChanged(), and selectedValueChanged() signals are emitted.

The optionRemoved() signal is emitted if the option is removed.

Parameters
option	The option to be removed.

Return:

true if the Option was removed, false otherwise.

Since:

BlackBerry 10.0.0

Q_SLOT void resetAcceptAction ()

Resets the accept button for this TitleBar.

This function removes the accept action button from the TitleBar. When this function completes, the acceptActionChanged() signal is emitted.

Since:

BlackBerry 10.0.0

Q_SLOT void resetAppearance ()

Resets the appearance of this TitleBar to bb::cascades::TitleBarAppearance::Type Default.

Since:

BlackBerry 10.0.0

Deprecated

BlackBerry 10.3.0

Q_SLOT void resetBranded ()

Resets the brand of this TitleBar to bb::cascades::TriBool::Type Undefined.

Since:

BlackBerry 10.0.0

Deprecated

BlackBerry 10.3.0

Q_SLOT void resetDismissAction ()

Resets the dismiss button for this TitleBar.

This function removes the dismiss action button from the TitleBar. When this function completes, the dismissActionChanged() signal is emitted.

Since:

BlackBerry 10.0.0

Q_SLOT void resetKindProperties ()

Resets the kind properties of the TitleBar to 0.

Since:

BlackBerry 10.1.0

Q_SLOT void resetSelectedIndex ()

Resets the selected index of the TitleBar.

The selected index is reset to 0 if the TitleBar has an Option selected at a non-zero index.

The selectedIndexChanged(), selectedOptionChanged(), and selectedValueChanged() signals are emitted, if the index was changed to 0.

Since:

BlackBerry 10.0.0

Q_SLOT void resetSelectedOption ()

Resets the selected option of the TitleBar.

The selected index is reset to 0 if the TitleBar has an Option selected at a non-zero index.

The selectedIndexChanged(), selectedOptionChanged(), and selectedValueChanged() signals are emitted, if the index was changed to 0.

Since:

BlackBerry 10.0.0

Q_SLOT void resetTitle ()

Resets the title of this TitleBar to QString::Null.

Since:

BlackBerry 10.0.0

Q_SLOT void resetVisibility ()

Resets the visibility of the TitleBar to ChromeVisibility::Default.

Since:

BlackBerry 10.0.0

bb::cascades::TitleBarScrollBehavior::Type scrollBehavior ()

Returns the TitleBarScrollBehavior object for the page.

Return:

The TitleBarScrollBehavior for the Page.

int selectedIndex ()

Returns the index of the currently selected option, or SelectedIndexNone if no option is selected.

Return:

The index of the selected option, or SelectedIndexNone if no option is selected.

Since:

BlackBerry 10.0.0

bb::cascades::Option * selectedOption ()

Returns the selected Option*, or 0 if no option is selected.

Return:

The selected Option*, or 0 if no option is selected.

Since:

BlackBerry 10.0.0

QVariant selectedValue ()

Returns the value of the currently selected option.

If no option is selected or no value is set on the selected option, an invalid QVariant is returned.

Return:

The value of the currently selected option or an invalid QVariant.

Since:

BlackBerry 10.0.0

Q_SLOT void setAcceptAction (
bb::cascades::ActionItem *acceptAction)

Sets the accept action for this TitleBar.

The TitleBar takes the ownership of the accept button.

If set to 0, the accept action is removed from this TitleBar.

When this function completes, the acceptActionChanged() signal is emitted.

Parameters
acceptAction	The action to be displayed on the side of the title.

Since:

BlackBerry 10.0.0

Q_SLOT void setAppearance (
bb::cascades::TitleBarAppearance::Typeappearance)

Sets the appearance of this TitleBar.

Parameters
appearance	The appearance of this TitleBar.

Since:

BlackBerry 10.0.0

Deprecated

BlackBerry 10.3.0

Q_SLOT void setBranded (
bb::cascades::TriBool::Typebranded)

Sets the brand of this TitleBar.

Parameters
branded	The brand of this TitleBar.

Since:

BlackBerry 10.0.0

Deprecated

BlackBerry 10.3.0

Q_SLOT void setDismissAction (
bb::cascades::ActionItem *dismissAction)

Sets the dismiss action for this TitleBar.

The TitleBar takes the ownership of the dismiss action.

If set to 0, the dismiss button is removed from the TitleBar.

When this function completes, the dismissActionChanged() signal is emitted.

Parameters
dismissAction	The action button to be displayed on the side of the title.

Since:

BlackBerry 10.0.0

Q_SLOT void setKindProperties (
bb::cascades::AbstractTitleBarKindProperties *kindProperties)

Sets the kind properties of the TitleBar.

Ownership will always be transferred to the TitleBar. If TitleBar already has kind properties, the old properties will still be owned by TitleBar and destroyed when TitleBar is destroyed.

Note that the kind and kindProperties must match.

Parameters
kindProperties	The kind properties of the TitleBar.

Since:

BlackBerry 10.1.0

Q_SLOT void setSelectedIndex (
intindex)

Selects the option at index.

The index must be greater than or equal to 0, less than count() and less than four. Otherwise, it is ignored.

The selectedIndexChanged(), selectedOptionChanged(), and selectedValueChanged() signals are emitted, if the selected index is changed.

Parameters
index	The index of the option to select.

Since:

BlackBerry 10.0.0

Q_SLOT void setSelectedOption (
bb::cascades::Option *option)

Selects the specified Option.

The Option must either belong to the TitleBar or be 0. Otherwise, it is ignored. Passing 0 resets the selected index to 0.

This function is equivalent to calling setSelectedIndex(indexOf(option)) assuming that the Option belongs to this TitleBar, or is 0.

The selectedIndexChanged(), selectedOptionChanged(), and selectedValueChanged() signals are emitted, if the selected option is changed.

Parameters
option	The option belonging to this TitleBar to select, or 0 to deselect any selected option.

Since:

BlackBerry 10.0.0

Q_SLOT void setTitle (
const QString &title)

Sets the text title of this TitleBar.

Parameters
title	The text title of this TitleBar.

Since:

BlackBerry 10.0.0

Q_SLOT void setVisibility (
bb::cascades::ChromeVisibility::Typevisibility)

Sets the visibility mode of this TitleBar.

Parameters
visibility	The visibility of the TitleBar.

Since:

BlackBerry 10.0.0

QString title ()

Returns the title of this TitleBar.

Return:

The title of this TitleBar.

Since:

BlackBerry 10.0.0

bb::cascades::ChromeVisibility::Type visibility ()

Returns the visibility mode of the TitleBar.

Return:

The visibility mode of the title bar, specified using the ChromeVisibility::Type enumeration.

Since:

BlackBerry 10.0.0

virtual bool event (
QEvent *event)

Overloaded to implement the event mechanism in Cascades.

Warning!

If this function is overridden, it must be called by the derived class for events to work properly in Cascades.

Parameters
event	The received event.

Return:

True if the received event was recognized and processed, false otherwise.

Since:

BlackBerry 10.0.0

void setObjectName (
const QString &name)

Sets the objectName property.

Parameters
name	The new name for the object.

Since:

BlackBerry 10.0.0

virtual Q_INVOKABLE QString toDebugString ()

Returns a debug string representing this object.

Return:

A debug string for the object.

Since:

BlackBerry 10.0.0

Q_INVOKABLE bb::cascades::UIConfig * ui ()

Returns the UIConfig for this ui object.

The UIConfig can be used to perform unit conversions from design units (du) and snapped design units (sdu) to pixels.

Ownership remains with Cascades.

C++ use:

Container *container1 = Container::create().background(Color::Red);
UIConfig *ui = container1->ui();
container1->setPreferredWidth(ui->du(12));
container1->setPreferredHeight(ui->du(5));

Container *container2 = Container::create().background(Color::Green);
container2->setPreferredWidth(ui->sdu(13.5));
container2->setPreferredHeight(ui->sdu(7.5));

Container *container3 = Container::create().background(Color::Blue);
container3->setPreferredWidth(ui->px(150));
container3->setPreferredHeight(ui->sdu(50));

Return:

The UIConfig for this ui object.

Since:

BlackBerry 10.3.0

Static Public Functions

Builder create (
TitleBarKind::Typekind)

Creates and returns a builder for constructing a TitleBar object.

Using the builder to create a TitleBar object.

Example:

 TitleBar::create()
     .visibility(ChromeVisibility::Visible);
     .title("Title")

Return:

A builder used for constructing a TitleBar object.

Since:

BlackBerry 10.0.0

Builder create (
TitleBarScrollBehavior::Typebehavior,
TitleBarKind::Typekind )

Protected Functions

(Only has inherited protected functions)

BaseObject (
QObject *parent)

Constructs an instance of BaseObject's subclass.

Parameters
parent	An optional parent, defaults to 0.

Since:

BlackBerry 10.0.0

virtual void connectNotify (
const char *signal)

Overloaded to implement the event mechanism in Cascades.

If this function is overridden, it must be called by the derived class for events to work properly in Cascades.

Parameters
signal	The connected signal.

Since:

BlackBerry 10.0.0

virtual void disconnectNotify (
const char *signal)

Overloaded to implement the event mechanism in Cascades.

If this function is overridden, it must be called by the derived class for events to work properly in Cascades.

Parameters
signal	The disconnected signal.

Since:

BlackBerry 10.0.0

Signals

void acceptActionChanged (
bb::cascades::ActionItem *acceptAction)

Emitted when the accept button has changed.

Parameters
acceptAction	The new accept button.

Since:

BlackBerry 10.0.0

void appearanceChanged (
bb::cascades::TitleBarAppearance::TypenewAppearance)

Emitted when the appearance of this TitleBar changes.

Parameters
newAppearance	The new appearance.

Since:

BlackBerry 10.0.0

Deprecated

BlackBerry 10.3.0

void brandedChanged (
bb::cascades::TriBool::TypenewBrand)

Emitted when the brand of this TitleBar changes.

Parameters
newBrand	The new brand.

Since:

BlackBerry 10.0.0

Deprecated

BlackBerry 10.3.0

void dismissActionChanged (
bb::cascades::ActionItem *dismissAction)

Emitted when the dismiss button has changed.

Parameters
dismissAction	The new accept button.

Since:

BlackBerry 10.0.0

void kindPropertiesChanged (
bb::cascades::AbstractTitleBarKindProperties *kindProperties)

Emitted when the kind properties of this TitleBar changes.

Parameters
kindProperties	The new kind related properties.

Since:

BlackBerry 10.1.0

void optionAdded (
bb::cascades::Option *option)

Emitted when an option has been added to the TitleBar.

Parameters
option	The option that has been added.

Since:

BlackBerry 10.0.0

void optionRemoved (
bb::cascades::Option *option)

Emitted when an option has been removed from the TitleBar.

Parameters
option	The option that has been removed, 0 if emitted by removeAll().

Since:

BlackBerry 10.0.0

void selectedIndexChanged (
intselectedIndex)

Emitted when the selected option has changed.

Parameters
selectedIndex	The index of the newly selected option, or SelectedIndexNone if no option is selected.

Since:

BlackBerry 10.0.0

void selectedOptionChanged (
bb::cascades::Option *selectedOption)

Emitted when the selected option has changed.

Parameters
selectedOption	The newly selected option, or 0 if no option is selected.

Since:

BlackBerry 10.0.0

void selectedOptionSetChanged (
boolselectedOptionSet)

Emitted when the selectedOptionSet property changes.

Parameters
selectedOptionSet	If true the TitleBar currently has a selected option, if false the TitleBar does not currently have a selected option.

Since:

BlackBerry 10.0.0

void selectedValueChanged (
const QVariant &selectedValue)

Emitted when the value of the selected option has changed.

Parameters
selectedValue	The value of the newly selected option, or an invalid QVariant if none is selected.

Since:

BlackBerry 10.0.0

void titleChanged (
const QString &title)

Emitted when the title of this TitleBar changes.

Parameters
title	The new title.

Since:

BlackBerry 10.0.0

void visibilityChanged (
bb::cascades::ChromeVisibility::TypenewVisibility)

Emitted when the visibility of the TitleBar changes.

Parameters
newVisibility	The new visibility.

Since:

BlackBerry 10.0.0

void creationCompleted ()

Emitted when this object is instantiated as a result of loading a QML document and creating the root node (only after the root component that caused this instantiation has completed construction), or when the object is being constructed from its builder class.

This signal indicates that the construction and initialization of the object has been completed, the properties are initialized, and any QML binding values have been assigned to the object.

This signal is not emitted when the object is constructed from C++ using the constructor. If the object is constructed using its builder class, the signal is emitted when the the builder class returns the fully constructed object.

This signal can be used when there is an activity that needs to be performed, such as a property state integrity verification after the object is instantiated from a QML document or a builder, but before control is returned to the application.

See also:

QmlDocument

Since:

BlackBerry 10.0.0

void objectNameChanged (
const QString &objectName)

This signal is emitted when the objectName property is changed.

See also:

QObject, BaseObject::objectName.

Since:

BlackBerry 10.0.0

TitleBar

Overview

Inheritance

QML properties

QML signals

Properties Index

Public Static Attributes Index

Public Functions Index

Static Public Functions Index

Protected Functions Index

Signals Index

Properties

bb::cascades::ActionItem acceptAction

bb::cascades::TitleBarAppearance::Type appearance

QDeclarativeListProperty options[read-only]

bb::cascades::TriBool::Type branded

bb::cascades::ActionItem dismissAction

bb::cascades::TitleBarKind::Type kind

bb::cascades::AbstractTitleBarKindProperties kindProperties

bb::cascades::TitleBarScrollBehavior::Type scrollBehavior

int selectedIndex

bb::cascades::Option selectedOption

bool selectedOptionSet[read-only]

QVariant selectedValue[read-only]

QString title

bb::cascades::ChromeVisibility::Type visibility

QDeclarativeListProperty< QObject > attachedObjects[read-only]

QString objectName

QObject parent[read-only]

bb::cascades::UIConfig ui[read-only]

Public Static Attributes

const int SelectedIndexNone ()

Public Functions

TitleBar (TitleBarKind::Typekind)

TitleBar (TitleBarScrollBehavior::Typebehavior, TitleBarKind::Typekind )

virtual~TitleBar ()

bb::cascades::ActionItem * acceptAction ()

Q_INVOKABLE void addOption (bb::cascades::Option *option)

bb::cascades::TitleBarAppearance::Type appearance ()

bb::cascades::TriBool::Type branded ()

bb::cascades::ActionItem * dismissAction ()

Q_INVOKABLE int indexOfOption (bb::cascades::Option *option)

Q_INVOKABLE void insertOption (intindex, bb::cascades::Option *option )

bool isSelectedOptionSet ()

bb::cascades::TitleBarKind::Type kind ()

bb::cascades::AbstractTitleBarKindProperties * kindProperties ()

Q_INVOKABLE bb::cascades::Option * optionAt (intindex)

Q_INVOKABLE int optionCount ()

Q_INVOKABLE void removeAllOptions ()

Q_INVOKABLE bool removeOption (bb::cascades::Option *option)

Q_SLOT void resetAcceptAction ()

Q_SLOT void resetAppearance ()

Q_SLOT void resetBranded ()

Q_SLOT void resetDismissAction ()

Q_SLOT void resetKindProperties ()

Q_SLOT void resetSelectedIndex ()

Q_SLOT void resetSelectedOption ()

Q_SLOT void resetTitle ()

Q_SLOT void resetVisibility ()

bb::cascades::TitleBarScrollBehavior::Type scrollBehavior ()

int selectedIndex ()

bb::cascades::Option * selectedOption ()

QVariant selectedValue ()

Q_SLOT void setAcceptAction (bb::cascades::ActionItem *acceptAction)

Q_SLOT void setAppearance (bb::cascades::TitleBarAppearance::Typeappearance)

Q_SLOT void setBranded (bb::cascades::TriBool::Typebranded)

Q_SLOT void setDismissAction (bb::cascades::ActionItem *dismissAction)

Q_SLOT void setKindProperties (bb::cascades::AbstractTitleBarKindProperties *kindProperties)

Q_SLOT void setSelectedIndex (intindex)

Q_SLOT void setSelectedOption (bb::cascades::Option *option)

Q_SLOT void setTitle (const QString &title)

Q_SLOT void setVisibility (bb::cascades::ChromeVisibility::Typevisibility)

QString title ()

bb::cascades::ChromeVisibility::Type visibility ()

virtual bool event (QEvent *event)

void setObjectName (const QString &name)

virtual Q_INVOKABLE QString toDebugString ()

Q_INVOKABLE bb::cascades::UIConfig * ui ()

Static Public Functions

Builder create (TitleBarKind::Typekind)

TitleBar (
TitleBarKind::Typekind)

TitleBar (
TitleBarScrollBehavior::Typebehavior,
TitleBarKind::Typekind )

Q_INVOKABLE void addOption (
bb::cascades::Option *option)

Q_INVOKABLE int indexOfOption (
bb::cascades::Option *option)

Q_INVOKABLE void insertOption (
intindex,
bb::cascades::Option *option )

Q_INVOKABLE bb::cascades::Option * optionAt (
intindex)

Q_INVOKABLE bool removeOption (
bb::cascades::Option *option)

Q_SLOT void setAcceptAction (
bb::cascades::ActionItem *acceptAction)

Q_SLOT void setAppearance (
bb::cascades::TitleBarAppearance::Typeappearance)

Q_SLOT void setBranded (
bb::cascades::TriBool::Typebranded)

Q_SLOT void setDismissAction (
bb::cascades::ActionItem *dismissAction)

Q_SLOT void setKindProperties (
bb::cascades::AbstractTitleBarKindProperties *kindProperties)

Q_SLOT void setSelectedIndex (
intindex)

Q_SLOT void setSelectedOption (
bb::cascades::Option *option)

Q_SLOT void setTitle (
const QString &title)

Q_SLOT void setVisibility (
bb::cascades::ChromeVisibility::Typevisibility)

virtual bool event (
QEvent *event)

void setObjectName (
const QString &name)

Builder create (
TitleBarKind::Typekind)

Builder create (
TitleBarScrollBehavior::Typebehavior,
TitleBarKind::Typekind )

BaseObject (
QObject *parent)

virtual void connectNotify (
const char *signal)

virtual void disconnectNotify (
const char *signal)

void acceptActionChanged (
bb::cascades::ActionItem *acceptAction)

void appearanceChanged (
bb::cascades::TitleBarAppearance::TypenewAppearance)

void brandedChanged (
bb::cascades::TriBool::TypenewBrand)

void dismissActionChanged (
bb::cascades::ActionItem *dismissAction)

void kindPropertiesChanged (
bb::cascades::AbstractTitleBarKindProperties *kindProperties)

void optionAdded (
bb::cascades::Option *option)

void optionRemoved (
bb::cascades::Option *option)

void selectedIndexChanged (
intselectedIndex)

void selectedOptionChanged (
bb::cascades::Option *selectedOption)

void selectedOptionSetChanged (
boolselectedOptionSet)

void selectedValueChanged (
const QVariant &selectedValue)

void titleChanged (
const QString &title)

void visibilityChanged (
bb::cascades::ChromeVisibility::TypenewVisibility)

void objectNameChanged (
const QString &objectName)