Segmented controls

A SegmentedControl is used for grouping a set of Option controls. Options in a SegmentedControl are displayed in a horizontal row.


Screen showing a SegmentedControl with three options.

When options are added to a SegmentedControl, the available space in the control is split evenly between the options, with up to four visible options at a time. Text can be added to each of the options using the Option::text property. If the option text is longer than the available space, it will be truncated.

When an option in a SegmentedControl is selected, the option is highlighted.

Sizing

Responding to option selection

A SegmentedControl has two signals that you can capture to listen for changes to the selected option. The selectedOptionChanged() and selectedIndexChanged() signals are emitted when the selected option has changed. The selectedOptionChanged() signal uses the selectedOption parameter to provide information about the newly selected option, such as the specified value or description of the option. The selectedIndexChanged() signal uses the selectedIndex parameter to provide information about the index path of the selected option, which is useful if you just need to know that an option has changed.

In QML, you can capture these signal using the onSelectedOptionChanged or onSelectedIndexChanged signal handlers. This example shows how to use onSelectedOptionChanged and output the value to the console.

// Create a SegmentedControl with three options
SegmentedControl {
    Option {
        id: option1
        text: "Option 1"
        selected: true
    }
    Option {
        id: option2
        text: "Option 2"
    }
    Option {
        id: option3
        text: "Option 3"
    }
    onSelectedOptionChanged: {
        // When the selected option changes, output the selection to
        // the console
        console.debug("The selected option is " + selectedOption)
    }
}

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

#include <bb/cascades/SegmentedControl>
#include <bb/cascades/Option>
//...

// Create a SegmentedControl and add three
// options. The mySegmentedControl object is 
// declared in the header as follows:
// SegmentedControl *mySegmentedControl;
mySegmentedControl = SegmentedControl::create()
            .add(bb::cascades::Option::create()
                .text("Option 1")
                .objectName("option1")
                .selected(true))
            .add(bb::cascades::Option::create()
                .text("Option 2")
                .objectName("option2"))
            .add(bb::cascades::Option::create()
                .text("Option 3")
                .objectName("option3"));
                
                
// 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 selectedOptionChanged() signal to the 
// handleSelectedOptionChanged() slot
connectResult = connect(mySegmentedControl,
                        SIGNAL(selectedOptionChanged(bb::cascades::Option*)), 
                        this, 
                        SLOT(handleSelectedOptionChanged(bb::cascades::Option*)));
                        
// This is only available in Debug builds
Q_ASSERT(connectResult);

//...    

// Create the handleSelectedOptionChanged() slot to capture
// the selectedOptionChanged() signal emitted by the SegmentedControl
void SegmentedControl::handleSelectedOptionChanged
    (bb::cascades::Option *selectedOption)
{
    // Output the selected option to the console
    qDebug() << "The selected option is " << selectedOption;
}

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

Segmented control example

The following example uses a SegmentedControl to change the text style of a label.

The SegmentedControl has three options, each of which changes the text style of the label to a different style from the TextStyles class:

Animated image showing a SegmentedControl used to control the text style applied to a Label.

main.qml

import bb.cascades 1.0
 
Page {
    titleBar: TitleBar {
        title: "SegmentedControl"
    }
    Container {
        layout: DockLayout {}
        // Create a SegmentedControl with three options
        SegmentedControl {
            Option {
                id: option1
                text: "Small text"
                selected: true
            }
            Option {
                id: option2
                text: "Title text"
            }
            Option {
                id: option3
                text: "Big text"
            }
            onSelectedOptionChanged: {
                // Use an if statement to change the text style of the 
                // Label based on the selection option
                if (selectedOption == option1) {
                    myLabel.textStyle.base = 
                        SystemDefaults.TextStyles.SmallText;
                } else if (selectedOption == option2) {
                    myLabel.textStyle.base = 
                        SystemDefaults.TextStyles.TitleText;
                } else {
                    myLabel.textStyle.base = 
                        SystemDefaults.TextStyles.BigText;
                }
            }
        }
        // Create a Label and set the label text and text style
        Label {
            id: myLabel
            horizontalAlignment: HorizontalAlignment.Center
            verticalAlignment: VerticalAlignment.Center
            text: "Segmented control"
            textStyle.base: SystemDefaults.TextStyles.SmallText
        }
    }
}

SegmentedRecipe.h

#ifndef SEGMENTEDRECIPE_H_
#define SEGMENTEDRECIPE_H_

#include <bb/cascades/Page>
#include <bb/cascades/Container>
#include <QObject>
#include <bb/cascades/SegmentedControl>
#include <bb/cascades/Label>


namespace bb { namespace cascades { class Application; }}

using namespace bb::cascades;

class SegmentedRecipe : public QObject
{
    Q_OBJECT

public:

    SegmentedRecipe(bb::cascades::Application *app);
        virtual ~SegmentedRecipe() {}

public slots:
	void handleSelectedOptionChanged
    (bb::cascades::Option *selectedOption);

private:

    // Declare the Page and
    // Container
    Container *colorContainer;
    Container *root;

    SegmentedControl *mySegmentedControl;
    Label *myLabel;

};

#endif /* SEGMENTEDRECIPE_H_ */

SegmentedRecipe.cpp

#include "SegmentedRecipe.h"
 
#include <bb/cascades/Application>
#include <bb/cascades/Container>
#include <bb/cascades/DockLayout>
#include <bb/cascades/Page>
#include <bb/cascades/SystemDefaults>
#include <bb/cascades/TextStyle>
#include <bb/cascades/TitleBar>
#include <bb/cascades/SegmentedControl>
#include <bb/cascades/Label>
#include <bb/cascades/Option>
 
using namespace bb::cascades;
 
SegmentedRecipe::SegmentedRecipe(bb::cascades::Application *app)
: QObject(app)
{

    Page *page = new Page();
 
    root = Container::create()
            .layout(new DockLayout());
 
    TitleBar *tbar = TitleBar::create().title("SegmentedControl");
    page->setTitleBar(tbar);
 
    // Create a SegmentedControl with three options
    // corresponding to the available text styles
    mySegmentedControl = SegmentedControl::create()
            .add(bb::cascades::Option::create()
                .text("Small text")
                .objectName("option1")
                .selected(true))
            .add(bb::cascades::Option::create()
                .text("Title text")
                .objectName("option2"))
            .add(bb::cascades::Option::create()
                .text("Big text")
                .objectName("option3"));
 
 
     // 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);
     
     connectResult = connect(mySegmentedControl, SIGNAL(selectedOptionChanged
                        (bb::cascades::Option*)), this, 
                        SLOT(handleSelectedOptionChanged(bb::cascades::Option*)));
            
    // This is only available in Debug builds
    Q_ASSERT(connectResult);
    
    myLabel = Label::create()
        .text("Segmented control")
        .horizontal(HorizontalAlignment::Center)
        .vertical(VerticalAlignment::Center)
        .textStyle(SystemDefaults::TextStyles::smallText());
 
    root->add(mySegmentedControl);
    root->add(myLabel);
    page->setContent(root);
    app->setScene(page); 
}

// Create the handleSelectedOptionChanged() slot to capture the
// selectedOptionChanged() signal emitted by the SegmentedControl
void SegmentedRecipe::handleSelectedOptionChanged
    (bb::cascades::Option *selectedOption)
{
   // Use an if statement to change the text style of the 
   // label based on the selection option
   if (selectedOption->objectName() == "option1") {
       myLabel->textStyle()->setBase(SystemDefaults::TextStyles::smallText());
   } else if (selectedOption->objectName() == "option2") {
       myLabel->textStyle()->setBase(SystemDefaults::TextStyles::titleText());
   } else {
       myLabel->textStyle()->setBase(SystemDefaults::TextStyles::bigText());
   }
}

main.cpp

#include "SegmentedRecipe.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 SegmentedRecipe(&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