Toggle buttons

A ToggleButton is a fixed-size switch control with two states: On and Off.


Screen showing a ToggleButton.

The appearance of a toggle button is predefined. The color, shape, and font are fixed and can't be changed.

Sizing

Image toggle buttons

In addition to the standard toggle button listed above, Cascades also includes an ImageToggleButton. Like a standard toggle button, an ImageToggleButton is a switch control used to switch between two states (such as "On" and "Off"). Instead of having a fixed appearance, an ImageToggleButton uses images to represent each of its visual states.

The different states for an ImageToggleButton are:

  • Unchecked and enabled (the default state)
  • Checked and enabled
  • Unchecked and disabled
  • Checked and disabled
  • Unchecked and actively being pressed
  • Checked and actively being pressed

The behavior of the images representing the visual states is handled automatically, so you don't have to add any extra code. If you specify an image for a specific state, that image is used when the control reaches that state.

If you don't specify an image for a visual state, the ImageToggleButton won't be visible during the respective state.

Sizing

Responding to checked state changes

A ToggleButton and an ImageToggleButton have a checkedChanged() signal that you can capture to listen for changes in the checked state of the control. The checkedChanged() signal is emitted when a toggle button is either checked or unchecked by a user.

In QML, you capture the signal using the onCheckedChanged signal handler. This example shows how to create a ToggleButton and use it to control an undefined task called myTask. The task in this sample is not defined, but could be loading a process, playing an animation, and more.

ToggleButton {
    onCheckedChanged: {
        // Control your task
        if (checked) {
            myTask.start();
        } else {
            myTask.stop();
        }
    }
}

Here's how to do the same thing in C++:

#include <bb/cascades/ToggleButton>
//...

// Create a ToggleButton
ToggleButton *myToggle = new ToggleButton();

// If any Q_ASSERT statement(s) indicate that the slot failed 
// to connect to the signal, make sure you know exactly why
// this has happened. This is not normal, and will cause your
// app to stop working
bool connectResult;

// Since the variable is not used in the app, this is 
// added to avoid a compiler warning
Q_UNUSED(connectResult);

// Connect the checkedChanged() signal to the
// handleCheckedChanged() slot
connectResult = QObject::connect(myToggle, 
                             SIGNAL(checkedChanged(bool)), 
                             this, 
                             SLOT(handleCheckedChanged(bool)));
        
// This is only available in Debug builds
Q_ASSERT(connectResult);
        
//...

// Create the handleCheckedChanged() slot to capture the
// checkedChanged() signal emitted by the ToggleButton
void ToggleButton::handleCheckedChanged(bool checked)
{
    // Control your task
    if (checked) {
        myTask->start();
    } else {
        myTask->stop();
    }
}

For more information on responding to signals, see Signals and slots.

Toggle buttons example

The following example creates two toggle controls: a ToggleButton and an ImageToggleButton.

The ImageToggleButton uses a series of images of a key-switch to represent the checked and enabled states of the control. When the app starts, the ImageToggleButton is unchecked and enabled. Pressing and holding the control changes its state to unchecked and pressed, then to checked and enabled when the press is released. Pressing and holding the control again reverses the action.

The ToggleButton is used to control the enabled state of the ImageToggleButton. When the ToggleButton is set to On, the ImageToggleButton is enabled. When the ToggleButton is unchecked, the ImageToggleButton is disabled and changes its image accordingly based on its own checked state. A red glow around the "HALT" button on the key-switch is used to indicate that the ImageToggleButton is disabled.

You can download the images for the sample here: images.zip

Animation showing the different states of an ImageToggleButton.

main.qml

import bb.cascades 1.0
 
Page {
    titleBar: TitleBar {
        title: "Toggle Buttons"
    }
    Container {
        layout: DockLayout {}
         
        Container {
            layout: StackLayout {}
            horizontalAlignment: HorizontalAlignment.Center
            verticalAlignment: VerticalAlignment.Center
             
            // Create the ImageToggleButton and specify
            // the images for each of the different states
            ImageToggleButton {
                id: imageTButton
                preferredHeight: 460
                preferredWidth: 300
                imageSourceDefault: 
                    "asset:///images/default.png"
                imageSourceChecked: 
                    "asset:///images/checked_enabled.png"
                imageSourceDisabledUnchecked: 
                    "asset:///images/unchecked_disabled.png"
                imageSourceDisabledChecked: 
                    "asset:///images/checked_disabled.png"
                imageSourcePressedUnchecked: 
                    "asset:///images/pressed.png"
                imageSourcePressedChecked: 
                    "asset:///images/pressed.png"
            }
            
            // Create a ToggleButton
            ToggleButton {
                topMargin: 30
                horizontalAlignment: HorizontalAlignment.Center
                checked: true
                onCheckedChanged: {
                    // Use an if statement to control the enabled
                    // state of the ImageToggleButton
                    if (checked) {
                        imageTButton.enabled = true
                    } else {
                        imageTButton.enabled = false
                    }
                }
            }
        }
    }
}

ToggleRecipe.h

#ifndef TOGGLERECIPE_H_
#define TOGGLERECIPE_H_

#include <QObject>
#include <bb/cascades/ToggleButton>
#include <bb/cascades/ImageToggleButton>

using namespace bb::cascades;

namespace bb { namespace cascades { class Application; }}

class ToggleRecipe: public QObject
{
    Q_OBJECT

public:
    ToggleRecipe(bb::cascades::Application *app);

private slots:
void onCheckedChanged(bool checked);

private:
	ToggleButton *mStandardToggle;
	ImageToggleButton *mImageTButton;

};

#endif /* TOGGLERECIPE_H_ */

ToggleRecipe.cpp

#include "ToggleRecipe.h"

#include <bb/cascades/Application>
#include <bb/cascades/Container>
#include <bb/cascades/DockLayout>
#include <bb/cascades/StackLayout>
#include <bb/cascades/Page>
#include <bb/cascades/ToggleButton>
#include <bb/cascades/ImageToggleButton>
#include <bb/cascades/TitleBar>

using namespace bb::cascades;

ToggleRecipe::ToggleRecipe(bb::cascades::Application *app)
: QObject(app)
{
    Page *page = new Page();
    TitleBar *tbar = TitleBar::create()
             .title("Toggle Buttons");
    page->setTitleBar(tbar);

    Container *root = Container::create()
             .layout(new DockLayout());

    // The recipe Container
    Container *recipeContainer = Container::create()
            .left(20.0).right(20.0)
            .horizontal(HorizontalAlignment::Center)
            .vertical(VerticalAlignment::Center)
            .layout(new StackLayout());

    // Create an ImageToggleButton and specify
    // the images for each of the different states
    mImageTButton = ImageToggleButton::create()
    		.preferredHeight(460)
    		.preferredWidth(300)
    		.imageDefault(Image(QUrl
                ("asset:///images/default.png")))
    		.imageChecked(Image(QUrl
                ("asset:///images/checked_enabled.png")))
    		.imageDisabledUnchecked(Image(QUrl
                ("asset:///images/unchecked_disabled.png")))
    		.imageDisabledChecked(Image(QUrl
                ("asset:///images/checked_disabled.png")))
    		.imagePressedUnchecked(Image(QUrl
                ("asset:///images/pressed.png")))
    		.imagePressedChecked(Image(QUrl
                ("asset:///images/pressed.png")));

    // Create a ToggleButton
    mStandardToggle = ToggleButton::create()
    		.topMargin(30)
    		.horizontal(HorizontalAlignment::Center)
    		.checked(true);


    // If any Q_ASSERT statement(s) indicate that the slot 
    // failed to connect to the signal, make sure you know
    // exactly why this has happened. This is not normal, and
    // will cause your app to stop working
    bool connectResult;
    
    // Since the variable is not used in the app, this is added 
    // to avoid a compiler warning
    Q_UNUSED(connectResult);
    
    // Connect the checkedChanged() signal to the
    // onCheckedChanged() slot
    connectResult = connect(mStandardToggle, 
                            SIGNAL(checkedChanged(bool)), 
                            this,
                            SLOT(onCheckedChanged(bool)));
                    
    // This is only available in Debug builds
    Q_ASSERT(connectResult);
                    
    // Add the controls to the recipe Container and set it as 
    // the root component
    recipeContainer->add(mImageTButton);
    recipeContainer->add(mStandardToggle);
    root->add(recipeContainer);
    page->setContent(root);
    app->setScene(page);
}

// Create the onCheckedChanged() slot to capture the checkedChanged()
// signal emitted by the ToggleButton
void ToggleRecipe::onCheckedChanged(bool checked)
{
    // Use an if statement to control the enabled state of the
    // ImageToggleButton
    if (checked) {
    	mImageTButton->setEnabled(true);
    } else {
    	mImageTButton->setEnabled(false);
    }
}

main.cpp

#include "ToggleRecipe.h"
 
#include <bb/cascades/Application>
#include <Qt/qdeclarativedebug.h>
 
using namespace bb::cascades;
 
Q_DECL_EXPORT int main(int argc, char **argv)
{
    Application app(argc, argv);
 
    new ToggleRecipe(&app);
 
    return Application::exec();
}

Last modified: 2013-12-21



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus