Home · All Classes · Main Classes · Deprecated
Signals | Public Member Functions | Properties

MButtonGroup Class Reference

MButtonGroup organizes groups of button widgets. More...

Inherits QObject.

List of all members.

Signals

void buttonClicked (MButton *button)
void buttonClicked (int id)
void buttonPressed (MButton *button)
void buttonPressed (int id)
void buttonReleased (MButton *button)
void buttonReleased (int id)

Public Member Functions

 MButtonGroup (QObject *parent=0)
virtual ~MButtonGroup ()
void addButton (MButton *button)
void addButton (MButton *button, int id)
MButtonbutton (int id) const
QList< MButton * > buttons () const
MButtoncheckedButton () const
int checkedId () const
bool exclusive (void) const
void setExclusive (bool)
int id (MButton *button) const
void removeButton (MButton *button)
void setId (MButton *button, int id)

Properties

bool exclusive

Detailed Description

MButtonGroup organizes groups of button widgets.

Overview

MButtonGroup does not provide a visual representation of this grouping, instead it manages the states of each of the buttons in the group. If visual representation for the buttons in a group is needed, MLinearLayoutPolicy::setNotifyWidgetsOfLayoutPositionEnabled() method can be used to enable the layout to automatically set background graphics for the buttons depending on their position.

An exclusive button group switches off all checkable (toggle) buttons except the one that was clicked. By default, a button group is exclusive. The buttons in a button group are usually checkable buttons. Non-checkable buttons can be added into group as well but they don't affect the button selection policy at all, however the interaction signals are emitted normally for them too.

If you create an exclusive button group, you should ensure that one of the buttons in the group is initially checked; otherwise, the group will initially be in a state where no buttons are checked.

A button is added to the group with addButton(). It can be removed from the group with removeButton(). If the group is exclusive, the currently checked button is available as checkedButton(). If a button is clicked the buttonClicked() signal is emitted. For a checkable button in an exclusive group this means that the button was checked. The list of buttons in the group is returned by buttons().

In addition, MButtonGroup can map between integers and buttons. You can assign an integer id to a button with setId(), and retrieve it with id(). The id of the currently checked button is available with checkedId(), and there is an overloaded signal buttonClicked() which emits the id of the button. The purpose of the mapping mechanism is to simplify the representation of enum values in a user interface.

Usage guidelines

Interactions

Open issues

Examples

Adding buttons to group:

        //create button group
        MButtonGroup* buttonGroup = new MButtonGroup();

        //add buttons to group
        MButton* buttons[5];
        for( int i=0; i < 5; ++i) {
            buttons[i] = new MButton("Button" + QString::number(i));
            buttons[i]->setViewType(MButton::toggleType);
            buttons[i]->setCheckable(true);
            buttonGroup->addButton(buttons[i]);
        }

        //connect to button interaction signals
        connect(buttonGroup, SIGNAL(buttonPressed(MButton*)), this, SLOT(groupButtonPressed(MButton*)));
        connect(buttonGroup, SIGNAL(buttonReleased(MButton*)), this, SLOT(groupButtonReleased(MButton*)));
        connect(buttonGroup, SIGNAL(buttonClicked(MButton*)), this, SLOT(groupButtonClicked(MButton*)));

        //you can add non-checkable buttons in group as well
        MButton* button = new MButton();
        buttonGroup->addButton(button);

        //and maybe later set them as checkable
        button->setCheckable(true);

        //remove button
        buttonGroup->removeButton(buttons[0]);

        //the group does not free the added buttons they need to be manually deleted by the user
        //when deleting a button it is automatically removed from the group it belongs
        delete button;
        for( int i=0; i<5; ++i)
            delete buttons[i];

User defined button ids in a group:

        //create button group
        MButtonGroup* buttonGroup = new MButtonGroup();

        //add buttons with user defined ids to group
        MButton* buttons[5];
        for( int i=0; i < 5; ++i) {
            buttons[i] = new MButton("Button" + QString::number(i));
            buttons[i]->setViewType(MButton::toggleType);
            buttons[i]->setCheckable(true);
            buttonGroup->addButton(buttons[i], i);
        }

        //connect to button interaction signals
        connect(buttonGroup, SIGNAL(buttonPressed(MButton*)), this, SLOT(groupButtonPressed(MButton*)));
        connect(buttonGroup, SIGNAL(buttonReleased(MButton*)), this, SLOT(groupButtonReleased(MButton*)));
        connect(buttonGroup, SIGNAL(buttonClicked(MButton*)), this, SLOT(groupButtonClicked(MButton*)));

        //when giving ids for buttons signals with button ids are emitted by buttongroup in
        //addition of the normal signals, when ids are not assigned these signals are not emitted
        connect(buttonGroup, SIGNAL(buttonPressed(int)), this, SLOT(groupButtonPressed(int)));
        connect(buttonGroup, SIGNAL(buttonReleased(int)), this, SLOT(groupButtonReleased(int)));
        connect(buttonGroup, SIGNAL(buttonClicked(int)), this, SLOT(groupButtonClicked(int)));

        //fetch button by id
        MButton* button = buttonGroup->button(2);

        //fetch id of a button
        int id = buttonGroup->id(button);

Group the buttons visually together:

        //create button group and horizontal layout for the buttons
        MButtonGroup* buttonGroup = new MButtonGroup();
        MLayout* layout = new MLayout;
        MLinearLayoutPolicy* policy = new MLinearLayoutPolicy(layout, Qt::Horizontal);

        //make the policy to set the backgrounds of the buttons
        policy->setNotifyWidgetsOfLayoutPositionEnabled(true);

        //add buttons to group and layout
        MButton* buttons[5];
        for( int i=0; i < 5; ++i) {
            buttons[i] = new MButton("Button" + QString::number(i));
            buttons[i]->setViewType(MButton::groupType); //optional, for creating buttons without margins
            buttonGroup->addButton(buttons[i]);
            policy->addItem(buttons[i]);
        }
See also:
MButton

Constructor & Destructor Documentation

MButtonGroup::MButtonGroup ( QObject parent = 0  ) 

Constructs a new, empty button group with the given parent.

MButtonGroup::~MButtonGroup (  )  [virtual]

Destroys the button group.


Member Function Documentation

void MButtonGroup::addButton ( MButton button  ) 

Adds the given button to the end of the group's internal list of buttons.

The group does not take the ownership of the button, the caller of the method is still responsible for releasing the button.

void MButtonGroup::addButton ( MButton button,
int  id 
)

Adds the given button to the button group, with the given id.

The group does not take the ownership of the button, the caller of the method is still responsible for releasing the button.

id can not be -1.

MButton * MButtonGroup::button ( int  id  )  const

Returns the button with the specified id, or 0 if no such button exists.

void MButtonGroup::buttonClicked ( MButton button  )  [signal]

This signal is emitted when the given button is clicked.

A button is clicked when it is first pressed and then released, or programmatically when MButton::click() is called.

See also:
MButton::clicked().
void MButtonGroup::buttonClicked ( int  id  )  [signal]

This signal is emitted when a button with the given id is clicked.

Buttons without id does not emit this signal.

void MButtonGroup::buttonPressed ( int  id  )  [signal]

This signal is emitted when a button with the given id is pressed down.

Buttons without id does not emit this signal.

void MButtonGroup::buttonPressed ( MButton button  )  [signal]

This signal is emitted when the given button is pressed down.

void MButtonGroup::buttonReleased ( MButton button  )  [signal]

This signal is emitted when the given button is released.

void MButtonGroup::buttonReleased ( int  id  )  [signal]

This signal is emitted when a button with the given id is released.

Buttons without id does not emit this signal.

QList< MButton * > MButtonGroup::buttons (  )  const

Returns the list of this group's buttons. This may be empty.

MButton * MButtonGroup::checkedButton (  )  const

Returns the button group's checked button, or 0 if no buttons are checked.

int MButtonGroup::checkedId (  )  const

Returns the id of the checkedButton(), or -1 if no button is checked or button without id is checked.

bool MButtonGroup::exclusive ( void   )  const

Returns true if the group is exclusive.

int MButtonGroup::id ( MButton button  )  const

Returns the id for the specified button, or -1 if no such button exists.

void MButtonGroup::removeButton ( MButton button  ) 

Removes the given button from the button group.

void MButtonGroup::setExclusive ( bool  exclusive  ) 

Set whether the button group is exclusive.

If the group is exclusive, then only one button in the group can be checked at any given time. The user can click on any button to check it, and that button will replace the existing one as the checked button in the group.

void MButtonGroup::setId ( MButton button,
int  id 
)

Sets the id for the specified button.

id can not be -1.


Property Documentation

bool MButtonGroup::exclusive [read, write]

Copyright © 2010 Nokia Corporation
MeeGo Touch