UIQ Controls - Scroll Bar

This guide explains how to add a scroll bar to a view. The means by which this is done is to add controls to a scrollable container. A Scroll Bar is used when the entire content of a control or view cannot be seen at one time. A Scroll Bar may be oriented horizontally or vertically. The control can be displayed with arrows only or with a shaft and thumb.

The following functionality can be used by the application developer:

• Change the length of the scroll bar,

• Change the position of the thumb,

• Change data model used by Scroll Bar,

• Toggle between dimming the entire control or not,

• Toggle between dimming all of the increase and decrease buttons, that is nudge, page, home and end buttons, or not.

During construction of the Scroll Bar it is possible to set a combination of the following parameters:

• Use standard system behavior,

• A Scroll Bar can be vertically or horizontally oriented,

• A scroll bar with nudge buttons,

• A scroll bar with page buttons,

• A scroll bar with home and end buttons,

• A scroll bar with shaft and thumb,

• A scroll bar with shaft but no thumb,

• Organize buttons at the start of the shaft,

• Organize buttons at the end of the shaft,

• Organize buttons at either end of the shaft,

• Scroll Bar with no automatic dimming of buttons.

Examples of Scroll Bar graphics:

Scroll Bar in Pen Style with thumb, page buttons, nudge buttons, home button and end button Scroll Bar in Pen Style with thumb and page buttons Scroll Bar in Pen Style in dimmed mode Scroll Bar in Softkey Style.

See the UIQ API Reference for the Scroll Bar class CEikScrollBar.

The Scroll Bar control is derived from Bordered Control. See the UIQ API Reference for the Bordered Control class (CEikBorderedControl).

Scroll Bar inherits from CEikBorderedControl.

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

Use the following #include directive:

#include <QikScrollableContainer.h>

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

LIBRARY qikcore.lib

3.2.1 QIK_VIEW_CONFIGURATIONS

This resource structure is used to define the configuration modes an application supports.

RESOURCE QIK_VIEW_CONFIGURATIONS
    {
    BYTE version = 0;
    STRUCT configurations[];
    }

3.2.2 QIK_VIEW_CONFIGURATION

This is a specific view configuration supported by the application. The recommended way to create a view is to specify the view and command list members inside each QIK_VIEW_CONFIGURATION. Then the framework will automatically switch view layout and commands when the window server changes mode. For more details see the Programmer's Guide for New Features in UIQ 3.

RESOURCE QIK_VIEW_CONFIGURATION
    {
    BYTE version = 0;
    LONG ui_config_mode = -1;
    LLINK command_list = -1;
    LLINK view = -1;    
    }

3.2.3 QIK_VIEW

The structure used to specify commands and controls of a view can either be linked from a QIK_VIEW_CONFIGURATION or be used as an argument to CQikViewBase::InitializeViewFromResourceL().

RESOURCE QIK_VIEW
    {
    BYTE version = 0;
    LLINK command_list = -1;
    LLINK pages = -1;   
    }

3.2.4 QIK_VIEW_PAGES

The pages of a view. Used by QIK_VIEW.

RESOURCE QIK_VIEW_PAGES
    {
    BYTE version = 0;
    STRUCT pages[]; 
    }

3.2.5 QIK_VIEW_PAGE

A page of a view. Used by QIK_VIEW_PAGE.

RESOURCE QIK_VIEW_PAGE
    {
    BYTE version = 1;
    WORD page_id = -1;
    LTEXT tab_caption = "";
    LTEXT tab_bmpfile = "*";
    WORD tab_bmpid = -1;
    WORD tab_bmpmaskid = -1;
    LLINK command_list = -1;
    LONG container_unique_handle = -1;
    LONG container_type = -1;
    LLINK container = -1;
    LLINK page_content = -1;    
    }

3.2.6 QIK_SCROLLABLE_CONTAINER_SETTINGS

The structure used by CQikScrollableContainer::InitializeFromResourceL() to set/change the controls the container contains and their layout.

Is referenced by QIK_VIEW_PAGE.page_content and QIK_CONTAINER_ITEM.container (and all the other container items).

RESOURCE QIK_SCROLLABLE_CONTAINER_SETTINGS
    {
    BYTE version = 0;
    LONG flags = EQikScrollableContainerDefaultFlags;
    LONG layout_manager_type = -1;
    LLINK layout_manager = -1;
    STRUCT controls[];  
    }

Possible flags:

    EQikContainerHandleRelayoutRequests
    EQikContainerPersistsAfterRelayout
    EQikContainerNonRowBasedMode                
    EQikContainerComponentsOwnedExternally          
    EQikContainerDebugMode
    
    EQikContainerHorizontalWrappingEnabled  
    EQikContainerVerticalWrappingEnabled            
    
    EQikContainerScrollHorizontalAuto           
    EQikContainerScrollHorizontalOn             
    EQikContainerScrollHorizontalOff            
    
    EQikContainerScrollHorizontalNormal     
    EQikContainerScrollHorizontalArrow          
    
    EQikContainerScrollVerticalAuto             
    EQikContainerScrollVerticalOn               
    EQikContainerScrollVerticalOff              
    
    EQikContainerScrollVerticalNormal       
    EQikContainerScrollVerticalArrow            

If you want to deviate from the standard flag settings, the only mandatory flag is EQikContainerHandleRelayoutRequests.

The recommended way to add scroll bar capabilities is to do it from a resource file.

Adding a scrollbar to a view is very simple. From your QIK_VIEW_PAGE::page_content simply point to a QIK_SCROLLABLE_CONTAINER_SETTINGS and add your controls to it.

Controls can be added from code or from the resource file. However, it is easiest and recommended to create the scrollable container from the resource file only.

3.3.1 Adding controls 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 controls' Id in a *.hrh file for use both in resource and cpp */
enum TMyViewControls
    {
    EMyViewScrollBar,
    EMyViewScrollableContainer,
    EMyViewBuildingBlock,
    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_scroll_bar_view_controls
    {
    items =
        {
        QIK_CONTROL
            {
            unique_handle = EMyViewScrollableContainer;
            type = EQikCtScrollableContainer;
            control = r_my_scroll_bar_scroll_pane;
            }
        };
    }

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

/* The view */
RESOURCE QIK_VIEW r_my_scroll_bar_view
    {
    pages = r_my_scroll_bar_viewpages;
    }
    
// The resource containing the pages
RESOURCE QIK_VIEW_PAGES r_my_scroll_bar_viewpages
    {
    pages=
        {
        // The page containing the controls in a scrollable container
        QIK_VIEW_PAGE
            {
            //Defining the type the container is
            container_unique_handle = EMyViewScrollableContainer;
            container_type = EQikCtScrollableContainer;
            container = r_my_scroll_bar_scroll_pane;
            
            // The container
            page_content=r_my_scroll_bar_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_scroll_bar_scroll_pane
    {
    }

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

RESOURCE QIK_SCROLLABLE_CONTAINER_SETTINGS r_my_scroll_bar_view_container_details
    {
    flags = EQikContainerHandleRelayoutRequests |
                EQikContainerPersistsAfterRelayout |
                EQikContainerScrollHorizontalOff |
                EQikContainerScrollHorizontalNormal |
                EQikContainerScrollVerticalOn |
                EQikContainerScrollVerticalNormal |
                EQikContainerVerticalWrappingEnabled;
    
    controls =
        {
        QIK_CONTAINER_ITEM_CI_LI
            {
            type = EQikCtCaptionedTwolineBuildingBlock;
            control = r_my_scroll_bar_building_block;
            }
        };
    }

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

RESOURCE QIK_SYSTEM_BUILDING_BLOCK r_my_scroll_bar_building_block
    {
    content =
        {
        QIK_SLOT_CONTENT
            {
            slot_id = EQikItemSlot1;
            caption = "Title above edwin control";
            },
        QIK_SLOT_CONTENT_DIRECT
            {
            slot_id = EQikItemSlot2;
            type=EEikCtEdwin;
            
            control =
                {
                EDWIN
                    {
                    flags=0;
                    width=10;
                    lines=1;
                    maxlength=25;
                    }
                };
            }
        };
    }

7) The configurations of the view:

RESOURCE QIK_VIEW_CONFIGURATIONS r_my_scroll_bar_ui_configurations
    {
    configurations=
        {
        QIK_VIEW_CONFIGURATION
            {
            ui_config_mode = KQikSoftkeyStylePortrait;
            view = r_my_scroll_bar_view;
            command_list = r_my_scroll_bar_commands;
            },
        QIK_VIEW_CONFIGURATION
            {
            ui_config_mode = KQikPenStyleTouchPortrait;
            view = r_my_scroll_bar_view;
            command_list = r_my_scroll_bar_commands;
            }
        };
    }

9) The command list for the view:

RESOURCE QIK_COMMAND_LIST r_my_scroll_bar_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_SCROLL_BAR_UI_CONFIGURATIONS, R_MY_SCROLL_BAR_VIEW_CONTROLS);
    }

3.3.2 Adding controls from code

Sometimes it is desirable to add controls dynamically from code. However, it is easiest to create the scrollable container from a resource file. Then you can add the controls to it from code.

CQikScrollableContainer* container = LocateControlByUniqueHandle<CQikScrollableContainer>(EContainer);

CQikBuildingBlock* block = CQikBuildingBlock::CreateSystemBuildingBlockL(EQikCtCaptionedHalflineBuildingBlock);
container->AddControlLC(block, 100);
block->ConstructL();
_LIT(KCaption,"Title above second edwin");
block->SetCaptionL(KCaption, EQikItemSlot1);

CEikEdwin* edwin = new (ELeave) CEikEdwin();    
block->AddControlLC(edwin, EQikItemSlot2);
edwin->ConstructL();
edwin->SetUniqueHandle(ELibraryBooksEdwinGenre);
edwin->SetObserver(this);    

CleanupStack::Pop(edwin);   
CleanupStack::Pop(block);

The Scroll Bar belongs to a control or a view, that is, it is used when all the content of the control or view cannot be seen at the same time. However, the interaction between the Scroll Bar and the control or view is handled by the framework, so the application developer does not need to be concerned about it.

There is no need for destroying the Scroll Bar. It is destroyed when the control or view it belongs to is destroyed.

Subclassing Scroll Bar is not recommended.