UIQ Controls - Duration Editor

This guide explains the UIQ Control Duration Editor (CQikDurationEditor). The Duration Editor allows the user to enter a duration of time in intervals of one or five minutes. The duration is selected by increasing or decreasing the hours and the minutes in a Duration Picker pop-out. The Duration Editor is almost identical with the Time Editor except that the Duration Editor even handles time periods greater than 24 hours.

The Duration Editor control displays the time duration. It has fields for hours and minutes as well as a localized time separator character, for example, a colon.

The user sets the duration with the Duration Picker pop-out control. How the pop-out is launched depends on the user interface style. In Pen Style UI, it is launched by a single tap on the Duration Editor. In Softkey Style UI a key is pressed.

Examples of Duration Editor and Duration Picker pop-up graphics:

The duration is selected by tapping the number field when using Pen Style UI. Tapping the top half of the number field increases the value, while tapping the bottom half of the number field decreases the value. The control ensures that the selected number falls within a specified range.

When using Softkey Style UI, the numeric key pad and the 4-way navigation key are used to select and edit the duration.

The preferred character used for the time separator is globally configured in the phone's locale settings.

Upper and lower time bounds for the control are set during initialization. Flags set during initialization can be used to suppress the Duration Picker pop-out or enable the Duration Picker pop-up to increase and decrease the time in five-minute intervals instead of the normal one-minute intervals.

The following functionality can be used:

• Set the minimum duration allowed,

• Set the maximum duration allowed,

• Set the duration,

• Set the interval to 1 minute or 5 minutes,

• Change the font to be used in the Duration Editor,

• Use the Duration Editor without a Duration Picker pop-out,

• Toggle between dimmed state and normal state,

• Change border properties.

By default, the following configuration applies:

• One-minute intervals,

• The font in the Duration Editor is set to the standard legend font for the system,

• The Duration Editor launches a Duration Picker pop-out,

• The control is not dimmed,

• The default system border is used,

• The information message for invalid input is "Invalid input".

• The information message for a duration shorter than the minimum duration is "Min time reached".

• The information message for a duration longer than the maximum duration is "Max time reached".

See the API documentation for Duration Editor CQikDurationEditor.

The Duration Editor control is related to the Time Editor, Date Editor and Time and Date Editor controls. See the How To guides for Time Editor and Date Editor.

See even the API documentation for Time Editor (CQikTimeEditor), Date Editor (CQikDateEditor) and Time and Date Editor (CQikTimeAndDateEditor).

The format that is displayed in Duration Editor is dependent on the locale settings. For more information about locale settings see Locale Settings in the Symbian OS guide.

Duration Editor inherits from CQikTTimeEditor and it has a CQikDurationPicker.

This section explains how Duration Editor is constructed, used and destroyed. Source code examples are used and explained to illustrate how the control is used.

Use the following #include directive:

#include <qikdurationeditor.h>

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

LIBRARY qikctl.lib

Use the following control identifier when specifying the control in resource data files. It is used by the framework when constructing the control from resource data:

EQikCtDurationEditor

Resource files can be used to construct the control. The resource to use is defined by the structure QIK_DURATION_EDITOR, defined in Qikon.rh. The structure looks like this:

STRUCT QIK_DURATION_EDITOR
    {
    STRUCT minDuration; // DURATION
    STRUCT maxDuration; // DURATION
    BYTE flags=0; // permitted flags: EQikTimeWithoutPopoutPicker
    }

STRUCT DURATION
    {
    LONG seconds=0; // must be greater than or equal to zero
    }

The values given in the structure definition are default values. The structure QIK_DURATION_EDITOR contains the following:

• minDuration - a structure of type DURATION,

• maxDuration - a structure of type DURATION,

• flags - this element is assembled by performing a bitwise OR with the flags listed below. Available flags are defined in Qikon.hrh.

The structure DURATION contains the following:

• seconds - The duration in number of seconds, must be greater than or equal to zero.

The control does not have any flags of its own, but the flags defined in the base class Time Editor (CQikTTimeEditor) can be used:

Time Editor (base class)- Resource flags Description EQikTimeWithoutPopoutPicker If set, the Duration pop-out is not used. The Duration Editor is then read-only. EQikTimeFiveMinuteSteps If set, the minutes are increased or decreased in five-minute intervals.

A common way to construct controls is to specify them in the resource files and let the framework construct them from there. Specifying the controls in resource files is the preferred way of constructing controls since it allows for easier modifications compared to creating them entirely from source code.

This section discusses four different ways of constructing controls. The first three ways describe how to construct and add a control to the view of an application. The view framework is used in all three cases but in three different ways. The fourth way describes how to construct and launch a dialog from an application. The dialog framework constructs the control and adds it into the dialog.

This section covers different ways of constructing the control.

3.3.1 Construction with View Framework Using Data from a Resource File

The example below describes how to construct the control using the view framework.

The reason the example seems to be rather complex is because it demonstrates how to construct a complete view containing a Scrollable Container and a Layout Manager. It also encapsulates the control in a Building Block. The view supports both pen and softkey styles; support of both styles in a view is optional.

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 the IDs of the controls in a *.hrh file for use both in resource and cpp */
enum TMyViewControls
    {
    EMyViewScrollableContainer,
    EMyViewBuildingBlock,
    EMyViewDurationEditor,
    EMyViewNumberOfControls
    };

2) Declare the controls to be used in the view in your resource (*.rss) file:

/* Declare the set of controls to be used in the view */
RESOURCE QIK_CONTROL_COLLECTION r_my_duration_editor_view_controls
    {
    items =
        {
        QIK_CONTROL
            {
            unique_handle = EMyViewScrollableContainer;     
            type = EQikCtScrollableContainer;           
            control = r_my_duration_editor_scroll_pane;
            },
        QIK_CONTROL
            {
            unique_handle = EMyViewDurationEditor;
            type = EQikCtDurationEditor;
            control = r_my_duration_editor;
            },
        QIK_CONTROL
            {
            unique_handle = EMyViewBuildingBlock;
            type = EQikCtCaptionedTwolineBuildingBlock;
            control = r_my_duration_editor_building_block;
            }
        };
    }

3) Define the view and its contents in your resource file:

/* The view */
RESOURCE QIK_VIEW r_my_duration_editor_view
    {
    pages = r_my_duration_editor_viewpages;
    }
                
/* The view page */
RESOURCE QIK_VIEW_PAGES r_my_duration_editor_viewpages
    {
    pages =
        {
        QIK_VIEW_PAGE
            {
            container_unique_handle = EMyViewScrollableContainer;
            page_content = r_my_duration_editor_view_container_details;
            }           
        };
    }

4) Define the resource for the Scrollable Container used in the view:

/* The scrollable container used in the view */
RESOURCE QIK_SCROLLABLE_CONTAINER r_my_duration_editor_scroll_pane
    {
    }

5) Declare the contents and properties for the Scrollable Container used in the view:

/* Contents of the Scrollable Container used in the view */
RESOURCE QIK_SCROLLABLE_CONTAINER_SETTINGS r_my_duration_editor_view_container_details
    {
    controls =
        {
        QIK_CONTAINER_ITEM
            {
            unique_handle = EMyViewBuildingBlock;
            }
        };
    }

6) Define the control resource structure used in the view:

/* The control used in the view */ 
RESOURCE QIK_DURATION_EDITOR r_my_duration_editor
    {
    minDuration =
        {
        DURATION
            {
            seconds = 0;
            }
        };
    maxDuration =
        {
        DURATION
            {
            seconds = 3600;
            }
        };
    flags = 0;
    }

7) Define the settings for the Building Block containing the control:

/* Settings for the EQikCtCaptionedTwolineBuildingBlock containing the control */   
RESOURCE QIK_SYSTEM_BUILDING_BLOCK r_my_duration_editor_building_block
    {
    content =
        {
        QIK_SLOT_CONTENT
            {
            slot_id = EQikItemSlot1;
            caption = "Choose:";
            },
        QIK_SLOT_CONTENT
            {
            slot_id = EQikItemSlot2;
            unique_handle = EMyViewDurationEditor;
            }
        };
    }

8) The configurations of the view:

RESOURCE QIK_VIEW_CONFIGURATIONS r_my_duration_editor_ui_configurations
    {
    configurations=
        {
        QIK_VIEW_CONFIGURATION
            {
            ui_config_mode = KQikSoftkeyStylePortrait;
            view = r_my_duration_editor_view;
            command_list = r_my_duration_editor_commands;
            },
        QIK_VIEW_CONFIGURATION
            {
            ui_config_mode = KQikPenStyleTouchPortrait;
            view = r_my_duration_editor_view;
            command_list = r_my_duration_editor_commands;
            }                       
        };
    }

9) The command list for the view:

RESOURCE QIK_COMMAND_LIST r_my_duration_editor_commands
    {
    items =
        {
        // This command shall only be visible in debug mode because it is only
        // used to find memory leaks during development of the application.
        QIK_COMMAND
            {
            id = EEikCmdExit;
            type = EQikCommandTypeScreen;
            // Indicate that this command will only be visible in debug
            stateFlags = EQikCmdFlagDebugOnly;
            text = "Close (debug)";
            }
        };
    }

10) The view framework constructs the view described in this example with this code:

void CMySinglePageView::ViewConstructL()
    {
    ViewConstructFromResourceL( R_MY_DURATION_EDITOR_UI_CONFIGURATIONS, R_MY_DURATION_EDITOR_VIEW_CONTROLS);
    }

11) The result should look something like this:

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

The example below describes how to construct a Duration Editor from resource with your own C++ code.

The reason the example seems to be rather complex is because it demonstrates how to construct a complete view containing a Scrollable Container and a Layout Manager. It also encapsulates the Duration Editor in a Building Block.

This example uses the resource structures from the previous example. The following code creates the Duration Editor:

#include <QikDurationEditor.h>
#include <QikRowLayoutManager.h>
#include <QikGridLayoutManager.h>
#include <QikBuildingBlock.h>
                    
void CMySinglePageView::ViewConstructL()
    {
    // Give a layout manager to the view
    CQikGridLayoutManager* gl = CQikGridLayoutManager::NewLC();
    SetLayoutManagerL(gl);
    CleanupStack::Pop(gl);      
                        
    // Create a container and give it to the view
    ControlProvider()->ControlInfos().AddFromResourceL(R_MY_DURATION_EDITOR_VIEW_CONTROLS);
    CQikContainerBase* container = static_cast<CQikContainerBase*>(ControlProvider()->ControlConstructIfNeededL(EMyViewScrollableContainer, *this));
    ASSERT(container);
    Controls().AppendLC(container);
    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 building block (containing a Duration Editor) and
    // add it to the container      
    CQikBuildingBlock* block = CQikBuildingBlock::CreateSystemBuildingBlockL(EQikCtCaptionedTwolineBuildingBlock);
    container->AddControlLC(block, EMyViewBuildingBlock);
    TResourceReader blockReader;
    iCoeEnv->CreateResourceReaderLC(blockReader, R_MY_DURATION_EDITOR_BUILDING_BLOCK);
    block->ConstructFromResourceL(blockReader, *ControlProvider());
    CleanupStack::PopAndDestroy(); //blockReader
    CleanupStack::Pop(block);
    }

What the code does

1) Initializes the Command Manager with an empty Command List. The controls 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) Loads the control collection R_MY_VIEW_CONTROLS into the Control Provider. Then the Control Provider is asked to create the Scrollable Container.

4) Uses the MopGetObjectNoChaining function to determine whether the control that was created really is a class of the type CQikContainerBase before it is added to the view.

5) Creates a Layout Manager to control the layout inside the container. Adds the Layout Manager to the container.

6) Constructs the Building Block containing the Duration Editor from the resource R_MY_BUILDING_BLOCK. Adds the Building Block to the container.

7) The result should look something like this:

The Duration Editor can also be created without a Building Block. In that case, replace the last section in the code above, from the "Create building block..." comment, with the following code.

Since a pointer to the control is declared here, QikDurationEditor.h needs to be included in the cpp-file and qikctl.lib in the mmp-file.

// Create the control and put it into the container
TResourceReader reader;
iEikonEnv->CreateResourceReaderLC(reader, R_MY_DURATION_EDITOR);
                    
CQikDurationEditor* durationEditor = new (ELeave) CQikDurationEditor();
container->AddControlLC(durationEditor, EMyViewDurationEditor);
                    
durationEditor->ConstructFromResourceL(reader);  
durationEditor->SetObserver(this);
durationEditor->SetUniqueHandle(EMyViewDurationEditor);
                    
CleanupStack::Pop(durationEditor);
CleanupStack::PopAndDestroy(); //reader

Use AddControlLC to add controls to a Scrollable Container. Add the controls as soon as they are created. Do not push them onto the Cleanup Stack before they are added. Do not pop them from the Cleanup Stack until they are fully constructed. A TCleanupItem created in AddControlLC will make sure that the control is both cleaned up and removed from the Components Array if a leave occurs before the control is fully constructed.

8) The result should look something like this:

3.3.3 Construction Solely from C++ Code

The example below describes how to construct a Duration Editor solely from C++ code.

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

The following source code constructs a Duration Editor:

#include <QikDurationEditor.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 control and add it to the container
    CQikDurationEditor* durationEditor = new (ELeave) CQikDurationEditor();
    container->AddControlLC(durationEditor, EMyViewDurationEditor);
                        
    // Create and initiate your own time variables.
    TTimeIntervalSeconds initDuration(120);
    TTimeIntervalSeconds exampleMaxDuration(3600*48);
    TTimeIntervalSeconds exampleMinDuration(0);
                                            
    // Do 2nd phase construction
    durationEditor->ConstructL(exampleMinDuration, exampleMaxDuration, initDuration, 0 /* flags*/);
                        
    durationEditor->SetObserver(this);
    durationEditor->SetUniqueHandle(EMyViewDurationEditor);
    CleanupStack::Pop(durationEditor);
    }

What the code does

1) Initializes the Command Manager with an empty Command List. The controls 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 Duration Editor control from C++ code. Sets the view, this, to be an observer of the Duration Editor. The view's base class, CQikViewBase, handles focus changes in its method HandleControlEventL. For more details see the section below on how to be notified with Control Events .

6) The result should look something like this:

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

The Duration Editor 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 structure see CEikDialog and DIALOG in the API documentation.

1) Declare a dialog resource containing the Duration Editor:

RESOURCE DIALOG r_my_duration_editor_dialog
    {
    title = "Test of control in dialog";
    flags = EEikDialogFlagWait;                 
    items =
        {
        DLG_LINE
            {
            prompt = "Duration Editor:";
            type = EQikCtDurationEditor;
            control = QIK_DURATION_EDITOR
                {
                minDuration =
                    {
                    DURATION
                        {
                        seconds = 0;
                        }
                    };
                maxDuration =
                    {
                    DURATION
                        {
                        seconds = 3600*24;
                        }
                    };
                    flags = 0;
                };
            }
        };
    }

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:

CEikDialog* dlg = new (ELeave) CEikDialog();
dlg->ExecuteLD(R_MY_DURATION_EDITOR_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 the ExcecuteLD function name.

3) The result should look something like this:

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
durationEditor->SetUniqueHandle(EMyViewDurationEditor);
            
// Get a pointer to the control
CQikDurationEditor* durationEditor = LocateControlByUniqueHandle<CQikDurationEditor>(EMyViewDurationEditor);

3.4.1 How to be Notified with Control Events

In order to be notified when the control changes state you must add an observer to the control. 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 control 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 control:

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

void CMySinglePageView::HandleControlEventL(CCoeControl* aControl, TCoeEvent aEventType)
    {
    // Call base class to handle focus management
    CQikViewBase::HandleControlEventL(aControl, aEventType);
                        
CQikDurationEditor* durationEditor = LocateControlByUniqueHandle<CQikDurationEditor>(EMyViewDurationEditor);
    
if(aControl == durationEditor)
        {
        switch(aEventType)
            {
            case EEventStateChanged:
                // The internal state of the Duration Editor was changed,
                // for example, due to another item being selected. 
                break;
                                    
            case EEventRequestExit:
                break;
                                    
            case EEventRequestCancel:
                break;
                                    
            case EEventRequestFocus:
                // The Duration Editor received a pointer down event
                break;
                                    
            case EEventPrepareFocusTransition:
                // A focus change is about to appear
                break;
                                
            case EEventInteractionRefused:
                // The Duration Editor 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 control's 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 the API documentation.

3.4.2 How to Set the Duration

Set the duration in the control by using the following code:

TTimeIntervalSeconds exampleDuration(60*5);
durationEditor->SetDurationL(exampleDuration);

3.4.3 How to Get the Duration

Get the duration from the control by using the following code:

TTimeIntervalSeconds exampleDuration = durationEditor->Duration();

3.4.4 How to Set the Minimum and Maximum Limits

Set the minimum and maximum duration values in the control by using the following code:

TTimeIntervalSeconds exampleMaxDuration(3600*48);
TTimeIntervalSeconds exampleMinDuration(60);
durationEditor->SetMinimumAndMaximum(exampleMinDuration, exampleMaxDuration);

3.4.5 How to Get the Minimum and Maximum Limits

Get the minimum and maximum duration values in the control by using the following code:

TTimeIntervalSeconds exampleMaxDuration;
TTimeIntervalSeconds exampleMinDuration;
durationEditor->GetMinimumAndMaximum(exampleMinDuration, exampleMaxDuration);

Destroying the control is just a matter of invoking operator delete on the Duration Editor object.

Subclassing Duration Editor is not recommended.