UIQ Controls - Check Box

This guide explains the UIQ control Check Box (CEikCheckBox). The Check Box is a control which allows the user to check or uncheck an option box. The following functionality can be set by the application developer:

• Enable tri-state mode. This adds the third control state, the filled state. By enabling tri-state mode the current state of the Check Box is changed to the filled state,

• Toggle between unchecked, checked and filled states, if tri-state mode is enabled.

Example of Check Box control graphics

Bitmaps Normal Dimmed Pressed Unchecked Checked Filled

See the API documentation for Check Box CEikCheckBox.

Labeled Check Box is very similar to Check Box. See the How To guide for Labeled Check Box.

See even the API documentation for Labeled Check Box CEikLabeledCheckBox.

Check Box inherits from CEikButtonBase.

This section explains how the control is constructed, used and destroyed.

Source-code examples are used and explained to illustrate how Check Box is used.

Use the following #include directive:

#include <eikchkbx.h>

Use the following LIBRARY directive in the project's mmp-file:

LIBRARY eikctl.lib

No resource structure is defined for the Check Box control.

You cannot create Check Box using all of the four ordinary ways, which are construction with view framework using data from a resource file, construction with your own C++ code using data from a resource file, construction solely from C++ code and construction with the dialog framework using data from a resource file.

A Check Box for a view can only be constructed from source code. The Check Box control is an exception because of the absence of a defined Check Box struct.

This section covers the one method of constructing a Check Box for a view and the one method for constructing a Check Box for a dialog.

3.3.1 Construction with View Framework Using Data from a Resource File

It is not possible to create a Check Box from resource in views. For creating Check Box from resource in dialogs see the section below.

3.3.2 Construction with Your Own C++ Code Using Data from a Resource File

Not applicable.

3.3.3 Construction Solely from C++ Code

The example below describes how to construct a Check Box solely from C++ code.

The reason the example seems to be rather complex is because it demonstrates how to construct a complete view with a Scrollable Container and a Layout Manager.

1) Declare an enumeration for the controls to be used in the view in a *.hrh file. Hrh files are files to be included both in resource files (*.rss) and C++ files.

/* Declare in the control ID *.hrh file for use both in resource and cpp */
enum TMyViewControls
    {
    EMyViewCheckBox
    };

2) The following source code constructs a Check Box.

#include <eikchkbx.h>
#include <QikScrollableContainer.h>
#include <QikRowLayoutManager.h>
#include <QikGridLayoutManager.h>
#include <QikBuildingBlock.h>
                
void CMySinglePageView::ViewConstructL()
    {
    // Give a layout manager to the view
    CQikGridLayoutManager* gridlayout = CQikGridLayoutManager::NewLC();
    SetLayoutManagerL(gridlayout);
    CleanupStack::Pop(gridlayout);
    
    // Create a container and add it to the view
    CQikScrollableContainer* container = new (ELeave) CQikScrollableContainer();
    Controls().AppendLC(container);
    container->ConstructL(EFalse);
    CleanupStack::Pop(container);
    
    // Create a layout manager to be used inside the container
    CQikRowLayoutManager* rowlayout = CQikRowLayoutManager::NewLC();
    container->SetLayoutManagerL(rowlayout);
    CleanupStack::Pop(rowlayout);
    
    // Create the Check Box and add it to the container
    CEikCheckBox* myCheckBox = new (ELeave) CEikCheckBox();
    container->AddControlLC(myCheckBox, EMyViewCheckBox);
    myCheckBox->SetObserver(this);
    myCheckBox->SetUniqueHandle(EMyViewCheckBox);
    
    // Set the state of the Check Box control with that specified by the data member.
    // CEikButtonBase::TState iState member need to be added in the header file,
    // you also need to include eikbutb.h for the CEikButtonBase::TState type.
    myCheckBox->SetState(iState);
    
    CleanupStack::Pop(myCheckBox);
    }

What the code does

1) Initializes the Command Manager with an empty Command List. The controls that are placed in the view add their Commands to the Command List when they receive focus.

2) Creates a Layout Manager for the view. The Grid Layout Manager fills the view with its only control in this example, the Scrollable Container.

3) Instantiates a Container and adds it to the view.

4) Creates a Layout Manager and adds it to the container.

5) Creates the Check Box control from C++ code. Sets the view, this, to be the observer of the Check Box. The view's base class, CQikViewBase, handles focus changes in its method HandleControlEventL. For more details see the section Getting notified below.

6) Sets the state of the control. Alternatively, the state of the control can be set by explicitly specifying the state using one of the three TState flags, defined in CEikButtonBase, as shown below.

// Set the state of Check Box to Set                    
iState = CEikCheckBox::ESet;
myCheckBox->SetState(iState);

// Set the state of Check Box to Clear  
iState = CEikCheckBox::EClear;
myCheckBox->SetState(iState);

// Set the state of Check Box to Indeterminate  
iState = CEikCheckBox::EIndeterminate;
myCheckBox->SetState(iState);    

Flags

There are no flags available in the CEikCheckBox class. However, there are some flags available which are inherited from the CEikButtonBase class.

CEikButtonBase - Flags in TState

EClear The clear state; often drawn at button-up. ESet The Set state; often drawn at button-down. EIndeterminate An indeterminate state; often used for an animation stage between the two other buttons, and may be used for derived tri-state buttons.

CEikButtonBase - Flags in TButtonBehavior

EEikbuttonStausClear Button is always clear. EEikButtonStaysSet Button is always set. EEikButtonLatches Button latches. EEikButtonReportsOnPointerDown Button reports a control event to its observer on just a pointer down rather than on a down followed by an up.

An example of how to set a flag on a Check Box:

myCheckBox->SetState(CEikCheckBox::EIndeterminate);

3.3.4 Construction with the Dialog Framework Using Data from a Resource File

Check Box can be constructed from resource files in dialogs as well. To construct a dialog from resource, a valid resource definition of that dialog must be in one of the project's resource files.

An example of a dialog resource containing the control is given below. For more information about the dialog class and its resource struct see CEikCheckBox and DIALOG in the API documentation.

1) Declare a dialog resource containing the Check Box control.

RESOURCE DIALOG r_checkBox_dialog
    {
    title="CheckBox Test";
    flags=EEikDialogFlagWait;
    items=
        {
        DLG_LINE
            {
            prompt="CheckBox:";
            type=EEikCtCheckBox;
            id=EMyCheckBoxControlId1;   
            }
        };
    }

The resource properties inside the Control Block are the same as the ones described in the previous section.

2) Launch the dialog using the following source code. The dialog resource ID is passed as an argument:

CControlTestDialog* dlg = new (ELeave)CControlTestDialog();
dlg->ExecuteLD(R_CHECKBOX_DIALOG);

The function returns immediately if EEikDialogFlagWait has not been specified in the dialog resource. If EEikDialogFlagWait is specified it returns when the dialog exits. The dialog framework will in both situations delete the dialog appropriately as indicated by the D suffix of theExcecuteLD function name.

This section covers the most common functions used for interacting with the control.

When constructing the control with resource data, no reference to the control is available in the view class. When constructing the control with code, the preferred way might be to not save a reference to the control. In both these cases, the LocateControlByUniqueHandle function is used to get a pointer to the control by supplying the control's unique Handle. When constructing the view and the control from code you must explicitly set this unique handle by calling the method SetUniqueHandle. See the code examples below.

Note that the function will return NULL if the control could not be found. Always check the pointer before using it!

// Set the unique handle
myCheckBox->SetUniqueHandle(EMyViewCheckBox);

// Get a pointer to the edwin control
CEikCheckBox* myCheckBox = static_cast<CEikCheckBox*>(LocateControlByUniqueHandle(EMyViewCheckBox));  

3.4.1 Getting the State of the Check Box

Extract the value from the Check Box control as follows:

// Get a pointer to the edwin control
CEikCheckBox* myCheckBox = static_cast<CEikCheckBox*>(LocateControlByUniqueHandle(EMyViewCheckBox));              
                                
// Get the state of the Check Box control and assign it to a data member.
iState = myCheckBox->State();

3.4.2 How to be Notified with Control Events

In order to be notified when the Check Box changes state you must add an observer to the Check Box. An observer is an object of the type MCoeControlObserver. The observer will then receive a function call to its function HandleControlEventL(CCoeControl* aControl, TCoeEvent aEventType) when the Check Box changes state.

The view base class, CQikViewBase, implements the MCoeControlObserver. The HandleControlEventL function must be overloaded in the view class, because the view inherits from CQikViewBase.

The following source code example shows how to add an object as an observer and how to receive events from the Check Box:

void CMySinglePageView::ViewConstructL()
    {
    // Construction code
    …
    // Adding this object as an observer
    lchkbx->SetObserver(this);
    }

void CMySinglePageView::HandleControlEventL(CCoeControl* aControl, TCoeEvent aEventType)
    {
    // Call base class to get focus navigation right
    CQikViewBase::HandleControlEventL(aControl, aEventType);
                    
    CEikCheckBox* chkbx = static_cast<CEikCheckBox*>(LocateControlByUniqueHandle(EMyViewCheckBox));
                    
    if(aControl == chkbx)
        {
        switch(aEventType)
            {
            case EEventStateChanged:
                // The internal state of the Check Box was changed,
                // for example, due to another item being selected. 
                break;
                                
            case EEventRequestExit:
                break;
                                
            case EEventRequestCancel:
                break;
                                
            case EEventRequestFocus:
                // The Check Box received a pointer down event
                break;
                                
            case EEventPrepareFocusTransition:
                // A focus change is about to appear
                break;
                            
            case EEventInteractionRefused:
                // The Check Box is dimmed and received a
                // pointer down event.
                break;
                            
            default:
                break;
            }
        }
    }

The reason for calling the base class's HandleControlEventL function is that the view base class CQikViewBase handles focus management between controls in the view. If the Check Box observer is not a class which derives from CQikViewBase, focus management must be resolved by the observer itself. If a control requests focus and does not get it from the observer it will generate a panic in some cases if the observer does not leave.

For more details on the TCoeEvent type, see class MCoeControlObserver in API documentation.

Destroying the control is just a matter of invoking operator delete on the Check Box object.

Subclassing Check Box is not recommended.