MButton implementation of a common button widget. More...

Inheritance diagram for MButton:

Collaboration diagram for MButton:

Public Slots
void	click ()
void	toggle ()
void	setIconVisible (bool)
void	setTextVisible (bool)
Signals
void	pressed ()
void	released ()
void	clicked (bool checked=false)
void	toggled (bool checked)
Public Member Functions
	MButton (QGraphicsItem parent=0, MButtonModel model=0)
	MButton (const QString &text, QGraphicsItem parent=0, MButtonModel model=0)
	MButton (const QString &iconID, const QString &text, QGraphicsItem parent=0, MButtonModel model=0)
virtual	~MButton ()
void	setIconID (const QString &iconID)
QString	iconID () const
void	setToggledIconID (const QString &toggledIconID)
QString	toggledIconID () const
void	setIcon (const QIcon &icon)
QIcon	icon () const
QString	text () const
void	setText (const QString &text)
bool	isTextVisible () const
bool	isIconVisible () const
bool	isCheckable () const
void	setCheckable (bool)
void	setDown (bool)
bool	isDown () const
bool	isChecked () const
void	setChecked (bool)
MButtonGroup *	group () const
Static Public Attributes
static const MTheme::ViewType	toggleType = "toggle"
static const MTheme::ViewType	checkboxType = "checkbox"
static const MTheme::ViewType	iconType = "icon"
static const MTheme::ViewType	switchType = "switch"
static const MTheme::ViewType	groupType = "group"
Protected Slots
void	modelClick ()
Properties
QString	text
QString	iconID
QString	toggledIconID
QIcon	icon
bool	textVisible
bool	iconVisible
bool	checkable
bool	checked
bool	down

Detailed Description

MButton implementation of a common button widget.

Overview

MButton provides functionality of check, toggle and push button types. A button can display a label containing text and an icon. setText() sets the text. setIconID() sets the logical icon identifier.

MButton provides the following states for buttons:

isDown() indicates whether the button is pressed down.
isChecked() indicates whether the button is checked. Only checkable buttons can be checked and unchecked (see below).

The difference between isDown() and isChecked() is as follows. When the user clicks a toggle button to check it, the button is first pressed then released into the checked state. When the user clicks it again (to uncheck it), the button moves first to the pressed state, then to the unchecked state (isChecked() and isDown() are both false).

MButton provides the following signals:

pressed() is emitted when the finger is inside the button.
released() is emitted when the finger is lifted.
clicked() is emitted when the button is tapped (pressed and then released), or when click() is called.
toggled() is emitted when the state of a toggle button changes.

Usage guidelines

Direct UI has several different styles of buttons:
- Push Buttons (with a "button style" borders around the button)
- Icon Buttons (which in general behaves like a button, but is not visualized with a button-style border)
- Switches / checkboxes (alters between "on" and "off" states of a particular item)
Push buttons are typically used with dialogs, notifications and main windows to invoke action. Push buttons are used to invoke action, for instance to have a "Call" button in a contact card or a "Send" button in a dialog.
Icon buttons are typically used in application toolbars, generally where space is at a premium.
Switches and checkboxes are typically used for functions that the user can set on and off.
Additionally, buttons can be presented by themselves, or linked together as a button group. See MButtonGroup for details.
Buttons do not support launching the object menu by long press.

Variants

Default button view. View is used to visualize standard push buttons and checkboxes.
Icon view. View is used to visualize icon buttons.

Open issues

The Switch has (TBD: check how well this works in practice) its own haptic feedback: switching button from off to on feels different than when switching from on to off.
A new variant for switch should be implemented if some animation is needed between on and off states.

Examples

Constructing different button variants:

            //push button with text
            MButton* pushButton = new MButton("Push Button");

            //checkbox
            MButton* checkbox = new MButton();
            checkbox->setViewType(MButton::checkboxType);
            checkbox->setCheckable(true);

            //toggle button
            MButton* toggleButton = new MButton("Toggle Button");
            toggleButton->setViewType(MButton::toggleType);
            toggleButton->setCheckable(true);

            //switch
            MButton* switch = new MButton();
            switch->setViewType(MButton::switchType);
            switch->setCheckable(true);

            //icon button
            MButton* iconButton = new MButton();
            iconButton->setViewType(MButton::iconType);

Connecting to user input signals:

            //receive user input event from push button
            MButton* pushButton = new MButton("Push Button");
            connect(pushButton, SIGNAL(clicked()), this, SLOT(buttonClicked()));
            connect(pushButton, SIGNAL(pressed()), this, SLOT(buttonPressed()));
            connect(pushButton, SIGNAL(released()), this, SLOT(buttonReleased()));

            //receive user input event from checkable buttons
            //(checkbox, togglebutton and switch)
            MButton* checkable = new MButton();
            checkable->setViewType(MButton::checkboxType);
            checkable->setCheckable(true);
            connect(checkable, SIGNAL(clicked(bool)), this, SLOT(checkableClicked(bool)));
            connect(checkable, SIGNAL(toggled(bool)), this, SLOT(checkableToggled(bool)));

Connecting to user input signals:

See also:: MButtonModel MButtonStyle MButtonGroup

Definition at line 142 of file corelib/widgets/mbutton.h.

Constructor & Destructor Documentation

MButton::MButton	(	QGraphicsItem *	parent = `0`,
		MButtonModel *	model = `0`
	)			`[explicit]`

Constructs a button without text.

Definition at line 67 of file mbutton.cpp.

    : MWidgetController(new MButtonPrivate, model == NULL ? new MButtonModel : model, parent)
{
    Q_D(MButton);

    d->init();
}

MButton::MButton	(	const QString &	text,
		QGraphicsItem *	parent = `0`,
		MButtonModel *	model = `0`
	)			`[explicit]`

Constructs a button with text.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 75 of file mbutton.cpp.

    : MWidgetController(new MButtonPrivate, model == NULL ? new MButtonModel : model, parent)
{
    Q_D(MButton);

    d->init(QString(), text);
}

MButton::MButton	(	const QString &	iconID,
		const QString &	text,
		QGraphicsItem *	parent = `0`,
		MButtonModel *	model = `0`
	)

Constructs a button with icon and text.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 83 of file mbutton.cpp.

    : MWidgetController(new MButtonPrivate, model == NULL ? new MButtonModel : model, parent)
{
    Q_D(MButton);

    d->init(iconID, text);
}

MButton::~MButton ( ) [virtual]

Destroys the button.

Definition at line 91 of file mbutton.cpp.

{
    Q_D(MButton);

    if (d->buttonGroup) {
        d->buttonGroup->removeButton(this);
    }
}

Member Function Documentation

void MButton::click ( ) [slot]

Performs a click.

All the usual signals associated with a click are emitted as appropriate. If the button is checkable, the state of the button is toggled.

Definition at line 221 of file mbutton.cpp.

{
    model()->setDown(true);
    model()->setDown(false);
    modelClick();
}

Here is the call graph for this function:

void MButton::clicked ( bool checked = false ) [signal]

This signal is emitted when the button is activated.

Notably, this signal is not emitted if you call setDown(), setChecked() or toggle().

If the button is checkable, checked is true if the button is checked, or false if the button is unchecked.

MButtonGroup * MButton::group ( ) const

Returns the group that this button belongs to.

If the button is not a member of any MButtonGroup, this function returns 0.

See also:: MButtonGroup.

Definition at line 233 of file mbutton.cpp.

{
    Q_D(const MButton);
    return d->buttonGroup;
}

QIcon MButton::icon ( ) const

Returns the icon of the button.

See also:: setIcon()

QString MButton::iconID ( ) const

Returns the logical ID of the icon of the button.

bool MButton::isCheckable ( ) const

Returns true if the button is checkable.

Definition at line 161 of file mbutton.cpp.

{
    return model()->checkable();
}

Here is the call graph for this function:

bool MButton::isChecked ( ) const

Returns true if the button is checked.

Definition at line 173 of file mbutton.cpp.

{
    return model()->checked();
}

Here is the call graph for this function:

bool MButton::isDown ( ) const

Returns true if the button is pressed down.

Definition at line 211 of file mbutton.cpp.

{
    return model()->down();
}

Here is the call graph for this function:

bool MButton::isIconVisible ( ) const

Returns true if the icon of the button is visible.

Definition at line 151 of file mbutton.cpp.

{
    return model()->iconVisible();
}

Here is the call graph for this function:

bool MButton::isTextVisible ( ) const

Returns true if the text of the button is visible.

Definition at line 141 of file mbutton.cpp.

{
    return model()->textVisible();
}

Here is the call graph for this function:

void MButton::modelClick ( ) [protected, slot]

Definition at line 279 of file mbutton.cpp.

{
    toggle();
    emit clicked(isChecked());
}

Here is the call graph for this function:

void MButton::pressed ( ) [signal]

This signal is emitted when the button is pressed down.

void MButton::released ( ) [signal]

This signal is emitted when the button is released.

void MButton::setCheckable ( bool buttonCheckable )

Set the button to be checkable.

By default, the button is not checkable.

Definition at line 166 of file mbutton.cpp.

{
    if (!buttonCheckable && model()->checked())
        model()->setChecked(false);
    model()->setCheckable(buttonCheckable);
}

Here is the call graph for this function:

void MButton::setChecked ( bool buttonChecked )

Sets the checked state of the button.

Only checkable buttons can be checked. By default, the button is unchecked.

Definition at line 181 of file mbutton.cpp.

{
    // FIXME: these checks could be done in model side, the group needs moved to model first
    if (isCheckable() && buttonChecked != isChecked()) {

        /* The active button in an exclusive group cannot be deselected */
        if (group() && group()->exclusive() && group()->checkedButton() == this) {
            return;
        }

        //TODO This is here just because of the delayed model initialization, this
        //     call should be removed when the delayed model initialization bug/feature
        //     is properly fixed.
        //
        //     The bug causes invalid functionaliy for buttons inside a buttongroup,
        //     if state of a button(s) is changed before messageloop is run first
        //     time. The updateData() slot does does not get called and toggled
        //     signal is not emitted. Exclusive buttongroup uses the toggled signal
        //     to uncheck buttons.
        bool shouldEmit = (model()->checked() != buttonChecked);
        toggleEmitted = false;

        model()->setChecked(buttonChecked);

        //TODO Remove this when delayed model initialization bug is properly fixed.
        if (shouldEmit && !toggleEmitted)
            emit toggled(model()->checked());
    }
}

Here is the call graph for this function:

void MButton::setDown ( bool status )

Set the button down state programmatically.

Unless you are implementing your own button type, you should not need to call this.

Definition at line 216 of file mbutton.cpp.

{
    model()->setDown(status);
}

Here is the call graph for this function:

void MButton::setIcon ( const QIcon & icon )

Sets the icon of the button.

See also:: icon(), setIconVisible(), setIconID()

Definition at line 121 of file mbutton.cpp.

{
    model()->setIcon(icon);
}

Here is the call graph for this function:

void MButton::setIconID ( const QString & iconID )

Sets the logical ID of the icon of the button.

Definition at line 100 of file mbutton.cpp.

{
    model()->setIconID(iconID);
}

Here is the call graph for this function:

void MButton::setIconVisible ( bool iconVisible ) [slot]

Set the visibility of the icon of the button.

Definition at line 156 of file mbutton.cpp.

{
    model()->setIconVisible(iconVisible);
}

Here is the call graph for this function:

void MButton::setText ( const QString & text )

Set the text of the button.

Definition at line 131 of file mbutton.cpp.

{
    model()->setText(text);
}

Here is the call graph for this function:

void MButton::setTextVisible ( bool textVisible ) [slot]

Set the visibility of the text of the button.

Definition at line 146 of file mbutton.cpp.

{
    model()->setTextVisible(textVisible);
}

Here is the call graph for this function:

void MButton::setToggledIconID ( const QString & toggledIconID )

Sets the logical ID of the toggled icon of the button.

Definition at line 111 of file mbutton.cpp.

{
    model()->setToggledIconID(toggledIconID);
}

Here is the call graph for this function:

QString MButton::text ( ) const

Returns the text of the button.

If the button has no text, the text() function will return an empty string.

There is no default text.

void MButton::toggle ( ) [slot]

Toggles the state of a checkable button.

Definition at line 228 of file mbutton.cpp.

{
    setChecked(!isChecked());
}

Here is the call graph for this function:

void MButton::toggled ( bool checked ) [signal]

This signal is emitted whenever a checkable button changes its state.

checked is true if the button is checked, or false if the button is unchecked.

This may be the result of a user action, click() slot activation, or because setChecked() was called.

QString MButton::toggledIconID ( ) const

Returns the logical ID of the toggled icon of the button.

Member Data Documentation

const MTheme::ViewType MButton::checkboxType = "checkbox" [static]

Variable that defines id for checkbox button variant.

Definition at line 210 of file corelib/widgets/mbutton.h.

const MTheme::ViewType MButton::groupType = "group" [static]

Variable that defines id for a buttons inside button groups.

Definition at line 225 of file corelib/widgets/mbutton.h.

const MTheme::ViewType MButton::iconType = "icon" [static]

Variable that defines id for icon button variant.

Definition at line 215 of file corelib/widgets/mbutton.h.

const MTheme::ViewType MButton::switchType = "switch" [static]

Variable that defines id for switch button variant.

Definition at line 220 of file corelib/widgets/mbutton.h.

const MTheme::ViewType MButton::toggleType = "toggle" [static]

Variable that defines id for toggle button variant.

Definition at line 205 of file corelib/widgets/mbutton.h.

Property Documentation

MButton::checkable [read, write]

See MButtonModel::checkable.

Definition at line 187 of file corelib/widgets/mbutton.h.

MButton::checked [read, write]

See MButtonModel::checked.

Definition at line 193 of file corelib/widgets/mbutton.h.

MButton::down [read, write]

See MButtonModel::down.

Definition at line 199 of file corelib/widgets/mbutton.h.

MButton::icon [read, write]

See MButtonModel::icon.

Definition at line 169 of file corelib/widgets/mbutton.h.

MButton::iconID [read, write]

See MButtonModel::iconID.

Definition at line 157 of file corelib/widgets/mbutton.h.

MButton::iconVisible [read, write]

See MButtonModel::iconVisible.

Definition at line 181 of file corelib/widgets/mbutton.h.

MButton::text [read, write]

See MButtonModel::text.

Definition at line 151 of file corelib/widgets/mbutton.h.

MButton::textVisible [read, write]

See MButtonModel::textVisible.

Definition at line 175 of file corelib/widgets/mbutton.h.

MButton::toggledIconID [read, write]

See MButtonModel::toggledIconID.

Definition at line 163 of file corelib/widgets/mbutton.h.

MButton Class Reference

Public Slots

Signals

Public Member Functions

Static Public Attributes

Protected Slots

Properties

Detailed Description

Overview

Usage guidelines

Variants

Open issues

Examples

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation

Property Documentation