Inheritance diagram

Collaboration diagram

Description

How to use

List box control(SFZListBoxControl) is a control to have a user select one item among list items.

Usage of the list box control

To insert an item, use the SFZListBoxControl::Insert / SFZListBoxControl::InsertFirst / SFZListBoxControl::InsertLast function. To remove an item, use the SFZListBoxControl::Remove / SFZListBoxControl::RemoveFirst / SFZListBoxControl::RemoveLast function. If the SFZListBoxControl::Clear function is called, all items are removed.

The selected item can be moved using the UP key set with the SFZListBoxControl::SetUpKey function or the DOWN key set with the SFZListBoxControl::SetDownKey function.

If the selected item is moved, the value event of SFXEvent(SFEVT_RESPONDER_VALUE, SFP16_VALUE_CURRENT, index of selected item) will be sent by the internal handler of this list box control.

	Note
	This value event will occur in the SFYControl::SetCurrentValue function called internally in SFZListBoxControl.

In the selected item, the text is drawn in the color set with the SFZListBoxControl::SetSelForeColor function, and the background is filled in the color set with the SFZListBoxControl::SetSelBackColor function.

In the unselected item, the text is drawn in the color set with the SFZListBoxControl::SetItemForeColor function, and the background is filled in the color set with the SFZListBoxControl::SetItemBackColor function.

The grid line can be drawn using the SFZListBoxControl::SetGridLineEnable and SFZListBoxControl::SetGridLineColor functions. The margin between two items can be set using the SFZListBoxControl::SetListMargin function.

In the default implementation, the list box control[SFZListBoxControl] will receive the following result events[SFEVT_RESPONDER_RESULT].

The developer can register handlers for these events.

The operation key is set with the SFYBoxControl::SetOperateKey function. By default, the operation key is set to the SELECT key.

The access key is set with the SFZListBoxControl::SetItemAccessKey function.

The ESCAPE key is set with the SFZListBoxControl::SetEscapeKey function. By default, the ESCAPE key is set to the CLEAR key.

	Caution
	The result event will not occur when the enable flag of selected item is set to "false" using the SFZListBoxControl::SetItemEnable function.

Reference: Result Event[SFEVT_RESPONDER_RESULT] | SFZListBoxControl::HandleOperateKey | SFZListBoxControl::HandleAccessKey | SFZListBoxControl::HandleEscapeKey

Limitation on specification

The minimum value is always 0. The current value represents the index of currently selected item. The maximum value represents the number of items. [* This function is to be discontinued in the future. To get the number of items, call the SFZListBoxControl::GetItemCount function.] The minimum value or the maximum value must not be changed by using the SFYControl::SetMinimumValue function or the SFYControl::SetMaximumValue function.

	Flex list box control
	The flex list box control of which functions are more advanced than the list box control is available. For more details, refer to SFZFlexListBoxControl.

Code to create the list box control

Void UserClass::Main(Void)
{
    SFZWindowSmp            window;
    SFZListBoxControlSmp    list;

    // create the window
    window = SFZWindow::NewInstance();
    window->SetParent(GetThis());
    window->SetBackgroundColor(SFXRGBColor(0xDD, 0xFF, 0xDD, 0x00));
    window->SetRealBound(GetLocalBound());
    window->SetState(true, true, true, true);

    // [Required] create list box control
    list = SFZListBoxControl::NewInstance(&error);

    // [Required] set list box control's parent responder to window
    list->SetParent(window);

    // [Required] insert 20 items at the tail
    for (SInt32 i = 0;  i < 20 ; ++i) {
        list->InsertLast(SFXWideString::Format("List Item %d ", i));
    }

    // [Optional] set grid line to enabled
    list->SetGridLineEnable(true);

    // [Optional] set grid line's color to black
    list->SetGridLineColor(SFXRGBColor(0x00, 0x00, 0x00, 0x00));

    // [Optional] set repeat-scroll flag to "true"
    list->SetScrollRepeat(true);

    // [Optional] set scroll bar's width to 7
    list->SetScrollBarWidth(7);

    // [Required] set list box control's real region to suitable size for given region
    list->SetRealBound(list->GetSuitableBound(_window->GetLocalBound().Deflate(30, 30)).SetOrigin(30, 30));

    // [Required] set list box control's state to "visible" + "active" + "enable" + "focus" together
    list->SetState(true, true, true, true);
    return;
}

Execution Result:

Reference

List Box Control [SFZListBoxControl] | SFZFlexListBoxControl | SFYBoxControl | SFZComboBoxControl | SFXEvent | State | Value Event[SFEVT_RESPONDER_VALUE]

Member

Description

This constructor performs the initializations as follows:

	Note
	In a responder inheriting from SFZListBoxControl, the corresponding handler will be called when one of the above events occurs.

Reference

SFYResponder::SetType | SFZListBoxControl::CodeEnum | SFZListBoxControl::SetDefaultItemBackColor | SFZListBoxControl::SetDefaultItemForeColor | SFZListBoxControl::SetSelBackColor | SFZListBoxControl::SetSelForeColor | SFZListBoxControl::SetGridLineColor | SFZListBoxControl::SetGridLineEnable | SFZListBoxControl::SetScrollRepeat | SFZListBoxControl::GetFieldValue | SFZListBoxControl::GetTopValue | SFZListBoxControl::SetFont | SFZListBoxControl::SetListMargin | SFZListBoxControl::SetScrollBarWidth SFZListBoxControl::SetScrollDirection | SFZListBoxControl::SetScrollInterval | SFZListBoxControl::SetScrollStep | SFZListBoxControl::SetWaitInterval | SFZListBoxControl::DirectionEnum | SFZListBoxControl::DefaultEnum | SFYBoxControl::SetOperateKey | SFZListBoxControl::SetItemAccessKey | SFZListBoxControl::HandleOperateKey | SFZListBoxControl::SetEscapeKey | SFZListBoxControl::HandleEscapeKey | SFZListBoxControl::SetUpKey | SFZListBoxControl::SetDownKey | SFXMargin | SFXRGBColor | SFXEvent | Type | Real Region | State | Event | Key Event[SFEVT_KEY] | Applet-Suspend Event[SFEVT_APP_SUSPEND] | Applet-Resume Event[SFEVT_APP_RESUME] | State Event[SFEVT_RESPONDER_STATE] | Value Event[SFEVT_RESPONDER_VALUE]

Description

Delete all items from this list box control.

Reference

SFZListBoxControl::Clear

Description

This function inserts an item at the tail of the list box control.

The numuber of items is set to the maximum value of the SFYControl class.

	Caution
	Since this function is deprecated, use the SFZListBoxControl::InsertLast function instead.

Reference

SFZListBoxControl::InsertLast | SFZListBoxControl::Remove | SFZListBoxControl::Clear | SFYControl::SetMaximumValue

Reference

SFZListBoxControl::Append SFZListBoxControl::Remove

Description

This function gets the default background color(SFXRGBColor) of unselected item of this list box control.

Reference

SFZListBoxControl::SetDefaultItemBackColor

Description

This function gets the default foreground color(SFXRGBColor) to draw the text of unselected item of this list box control.

Reference

SFZListBoxControl::SetDefaultItemForeColor

Return value

DOWN key to move the selected item down by one item, which is set by the SFZListBoxControl::SetDownKey function.

Reference

SFZListBoxControl::SetDownKey | SFZListBoxControl::GetUpKey | SFZListBoxControl::SetUpKey

Return value

ESCAPE key set with the SFZListBoxControl::GetEscapeKey function.

Reference

SFZListBoxControl::GetEscapeKey

Description

This function gets the number of items of this list box control which can be displayed at the same time.

This number is calculated using the height, the list margin, or the font of this list box control.

Reference

SFZListBoxControl::SetListMargin | SFZListBoxControl::SetFont

Return value

Font set with the SFZListBoxControl::SetFont function.

Description

This function gets the font of this list box control.

Reference

SFZListBoxControl::SetFont

Return value

Color(SFXRGBColor) of grid line of this list box control.

Reference

SFZListBoxControl::SetGridLineColor | SFZListBoxControl::SetGridLineEnable

Return value

Value of the enable flag of the grid line of this list box control.

Reference

SFZListBoxControl::SetGridLineEnable | SFZListBoxControl::SetGridLineColor

Description

This function gets the access key of the specified item of this list box control. AVK_UNDEFINED will be returned if the access key is not set.

Reference

SFZListBoxControl::SetItemAccessKey

Description

This function gets the background color(SFXRGBColor) of the specified unselected item of this list box control.

Reference

SFZListBoxControl::SetItemBackColor

Return value

Number of the items of this list box control.

Return value

Description

This function gets the value of enable flag of the specified item of this list box control. If the item is valid, "true" will be returned. Otherwise "false" will be returned.

Reference

SFZListBoxControl::SetItemEnable

Description

This function gets the foreground color(SFXRGBColor) to draw the text of the specified unselected item of this list box control.

Reference

SFZListBoxControl::SetItemForeColor | SFXRGBColor

Description

This function gets the item height of this list box control. [pixels]

Reference

SFZListBoxControl::SetFont | SFZListBoxControl::SetListMargin

Return value

Key icon(icon character) of the WChar type of the specified item of this list box control.

Reference

SFZListBoxControl::SetItemKeyIcon

Return value

Text of the specified item of this list box control.

Reference

SFZListBoxControl::SetItemText

Return value

Margin(SFXMargin) within each item of this list box control

Reference

SFZListBoxControl::SetListMargin

Return value

Number of items of this list box control.

Description

This function gets the scroll bar control, which this list box control contains internally.

The developer can change the appearance the scroll bar control such as its color using the scroll bar control obtained.

The scroll bar control of the developer's own can be set using the SFZListBoxControl::SetScrollBarControl function.

Example

The code below is to get the scroll bar control used by the list box control.

// get the scroll bar control
SFZListBoxControlSmp    _list;
SFYScrollBarControlSmp  _bar;

_list = SFZListBoxControl::NewInstance();

if ((_bar = _list->GetScrollBarControl()) != null) {
    _bar->SetTrackColor(SFXRGBColor(0xDD, 0xFF, 0xDD, 0x00));
}

Reference

SFYScrollBarControl | SFZListBoxControl::SetScrollBarControl

Return value

Width of the scroll bar control, which this list box control contains internally. [pixels]

Reference

SFZListBoxControl::SetScrollBarWidth

Return value

Scroll direction(SFZListBoxControl::DirectionEnum) set with the SFZListBoxControl::SetScrollDirection function.

Reference

SFZListBoxControl::SetScrollDirection | SFZListBoxControl::DirectionEnum

Return value

Scroll-interval set with the SFZListBoxControl::SetScrollInterval function. [milliseconds]

Reference

SFZListBoxControl::SetScrollInterval

Return value

Reference

SFZListBoxControl::SetScrollRepeat

Return value

Scroll-step set with the SFZListBoxControl::SetScrollStep function. [pixels]

Reference

SFZListBoxControl::SetScrollStep

Return value

Background color(SFXRGBColor) of currently selected item of this list box control, in which the rectangle containing the currently selected item is filled.

Reference

SFZListBoxControl::SetSelBackColor | SFZListBoxControl::GetSelForeColor | SFZListBoxControl::SetSelForeColor | SFXRGBColor

Return value

Foreground color(SFXRGBColor) of currently selected item of this list box control.

Reference

SFZListBoxControl::SetSelForeColor | SFZListBoxControl::GetSelBackColor | SFZListBoxControl::SetSelBackColor | SFXRGBColor

Return value

Index of the item of this list box control, which is currently displayed at the top.

Return value

UP key to move the selected item up by one item, which is set by the SFZListBoxControl::SetUpKey function.

Reference

SFZListBoxControl::SetUpKey | SFZListBoxControl::GetDownKey | SFZListBoxControl::SetDownKey

Return value

Waiting time to start the scroll set with the SFZListBoxControl::SetWaitInterval function. [milliseconds]

Reference

SFZListBoxControl::SetWaitInterval

Description

This function will be called when the SFEVT_KEY event(key event[SFEVT_KEY]) of the access key set with the SFZListBoxControl::SetItemAccessKey function is received.

In case you want to perform your own processing, override this function.

The default implementation is as follows:

	Note
	If the same access key is set to more than one item, only the setting of the first item is valid.

Internal Implementation

Internal implementation of the SFZListBoxControl::HandleAccessKey function is as follows:

struct ListItem {
    SFXWideString                       text;
    AVKType                             key;
    WChar                               keyIcon;
    SFXRGBColor                         foreColor;
    SFXRGBColor                         backColor;
    Bool                                enable;
};

ListItemArray                   _item;

/*protected virtual */Void SFZListBoxControl::HandleAccessKey(AVKType key)
{
    ListItemPtr                                 item;

    for (SInt32 i = 0; i < GetItemCount(); ++i) {
        if ((item = GetListItem(i)) != null) {
            if (item->key == key) {
                if (item->enable) {
             SetCurrentValue(i);
                    Invalidate();
                    InvokeForward(SFXEvent(SFEVT_RESPONDER_RESULT, SFP16_RESULT_OK, i), false);
                    break;
                }
            }
        }
    }
    return;
}// SFZListBoxControl::HandleAccessKey //

/*private */SFZListBoxControl::ListItemPtr SFZListBoxControl::GetListItem(SInt32 param) const
{
    ListItemPtr                                 result(null);

    if (0 <= param && param < GetItemCount()) {
        result = _item.Get(param);
    }
    return result;
}// SFZListBoxControl::GetListItem //

Reference

SFZListBoxControl::SetItemAccessKey | SFZListBoxControl::SetItemEnable | SFYControl::GetCurrentValue | SFXEvent | Result Event | Key Event[SFEVT_KEY]

Description

This function will be called when the region event [SFXEvent(SFEVT_RESPONDER_BOUND, SFP16_BOUND_OPTIMIZE, rectangle)] is received.

This function calculates the suitable rectangle size of this responder within the specified hint rectangle[i.e., rectangle element (P32 parameter) of the region event].

The suitable rectangle size is stored into the size element of the rectangle argument as a result of calculation. It is recommended not to change the origin of the rectangle argument in this function.

	Region event[(SFEVT_RESPONDER_BOUND, SFP16_BOUND_OPTIMIZE) event]
	If the rectangle argument of the hint region is specified, the SFYResponder::GetSuitableBound function will send the region event [SFXEvent(SFEVT_RESPONDER_BOUND, SFP16_BOUND_OPTIMIZE, rectangle)] to this responder. Then, the SFYWidget::HandleBoundOptimize virtual function will be called. The rectangle element (P32 parameter) of the region event is set to the hint region as an initial value.

Internal Implementation

Internal implementation of the SFZListBoxControl::HandleBoundOptimize function is as follows:

struct ListItem {
    SFXWideString                       text;
    AVKType                             key;
    WChar                               keyIcon;
    SFXRGBColor                         foreColor;
    SFXRGBColor                         backColor;
    Bool                                enable;
};

/*protected virtual */Void SFZListBoxControl::HandleBoundOptimize(SFXRectanglePtr rectangle) const
{
    ListItemPtr                                 item;
    SInt16                                      width;
    SInt16                                      maxWidth;
    SInt16                                      barWidth;
    SInt16                                      height;
    SInt32                                      num;

    maxWidth = 0;
    barWidth = 0;
    height = GetItemHeight();
    rectangle->Deflate(GetBoxMargin());
    num = rectangle->GetHeight() / height;
    if (num > 0) {
        if (num < GetItemCount()) {
            barWidth = _barWidth;
        }
        else {
            num = GetItemCount();
        }
        rectangle->SetHeight(static_cast<SInt16>(height * num));
    }
    for (SInt32 i = 0; i < GetItemCount(); ++i) {
        if ((item = GetListItem(i)) != null) {
            width = SFXGraphics::MeasureSingleText(_font, item->text);
            if (item->keyIcon != null) {
                width += GetFontSize().GetWidth();
            }
            maxWidth = (maxWidth < width) ? width : maxWidth;
        }
    }
    maxWidth += barWidth;
    rectangle->Deflate(GetListMargin());
    if (maxWidth < rectangle->GetWidth()) {
        rectangle->SetWidth(maxWidth);
    }
    rectangle->Inflate(GetListMargin());
    rectangle->Inflate(GetBoxMargin());
    return;
}// SFZListBoxControl::HandleBoundOptimize //

Reference

SFYResponder::GetSuitableBound | SFZListBoxControl::SetFont | SFZListBoxControl::SetItemKeyIcon | SFZListBoxControl::SetItemText | SFZListBoxControl::SetListMargin | SFZListBoxControl::SetScrollBarWidth | SFYBoxControl::GetBoxMargin | SFXMargin | SFXEvent | Region Event[SFEVT_RESPONDER_BOUND] | Handler for the Region Event[XANDLER_DECLARE_VOIDBOUND]

Description

This function will be called when the region event [SFXEvent(SFEVT_RESPONDER_BOUND, SFP16_BOUND_REQUEST, rectangle)] is received.

This function calculates the suitable rectangle size of this responder.

The suitable rectangle size is stored into the size element of the rectangle argument as a result of calculation. It is recommended not to change the origin element of the rectangle argument within this function.

Region event[(SFEVT_RESPONDER_BOUND, SFP16_BOUND_REQUEST) event]

If the rectangle argument of the hint region is not specified, the SFYResponder::GetSuitableBound function will send the region event [SFXEvent(SFEVT_RESPONDER_BOUND, SFP16_BOUND_REQUEST, rectangle)] to this responder. Then, the SFYWidget::HandleBoundRequest virtual function will be called. The rectangle element (P32 parameter) of the region event is set to the real region as an initial value. Tip Default value of the real region: SFXRectangle(0, 0, 0, 0)

Internal Implementation

Internal implementation of the SFZListBoxControl::HandleBoundRequest function is as follows:

struct ListItem {
    SFXWideString                       text;
    AVKType                             key;
    WChar                               keyIcon;
    SFXRGBColor                         foreColor;
    SFXRGBColor                         backColor;
    Bool                                enable;
};

/*protected virtual */Void SFZListBoxControl::HandleBoundRequest(SFXRectanglePtr rectangle) const
{
    ListItemPtr                                 item;
    SInt16                                      width;
    SInt16                                      maxWidth;

    maxWidth = 0;
    rectangle->Deflate(GetBoxMargin());
    for (SInt32 i = 0; i < GetItemCount(); ++i) {
        if ((item = GetListItem(i)) != null) {
            width = SFXGraphics::MeasureSingleText(_font, item->text);
            if (item->keyIcon != null) {
                width += GetFontSize().GetWidth();
            }
            maxWidth = (maxWidth < width) ? width : maxWidth;
        }
    }
    rectangle->SetHeight(static_cast<SInt16>(GetItemHeight() * GetItemCount()));
    rectangle->Deflate(GetListMargin());
    rectangle->SetWidth(maxWidth);
    rectangle->Inflate(GetListMargin());
    rectangle->Inflate(GetBoxMargin());
    return;
}// SFZListBoxControl::HandleBoundRequest //

Reference

SFYResponder::GetSuitableBound | SFZListBoxControl::SetFont | SFZListBoxControl::SetItemKeyIcon | SFZListBoxControl::SetItemText | SFZListBoxControl::SetListMargin | SFYBoxControl::GetBoxMargin | SFXMargin | SFXEvent | Real Region Region Event[SFEVT_RESPONDER_BOUND] | Handler for the Region Event[XANDLER_DECLARE_VOIDBOUND]

Description

This function will be called when the (SFEVT_RESPONDER_BOUND, SFP16_BOUND_VIRTUAL) event is received.

In case you want to perform your own processing when the virtual region is changed, override this virtual function.

The default implementation is to equalize the real region with the new local region and relocate this responder to fit into the new virtual region.

	Sending the (SFEVT_RESPONDER_BOUND, SFP16_BOUND_VIRTUAL) event
	The (SFEVT_RESPONDER_BOUND, SFP16_BOUND_VIRTUAL) event will occur when the virtual region is changed by calling the SFYResponder::SetRealBound or SFYResponder::SetVirtualBound function.

Another method when the virtual region is changed

Other than overriding this virtual function, it is possible to define and implement the handler for region event[XANDLER_DECLARE_VOIDBOUND], and register it into the responder. In the processing when the virtual region is updated, this virtual function is executed first, and next the handlers for region event are executed in the registered order. In almost all cases, the method to override this virtual function is adopted since defining, implementing and registering the handler for region event can be omitted.

Internal Implementation

Internal implementation of the SFZListBoxControl::HandleBoundVirtual function is as follows:

/*protected virtual */Void SFZListBoxControl::HandleBoundVirtual(Void)
{
    SFXMargin                                   margin(GetBoxMargin());
    SInt32                                      field;

    StopScroll();
    field = (GetLocalBound().GetHeight() - margin.GetTop() - margin.GetBottom()) / GetItemHeight();
    field = (field > 0) ? field : 1;
    SetFieldValue(field);
    _offset = 0;
    Relocate();
    if (_state != STATE_IDLE) {
 StartScroll();
    }
    return;
}// SFZListBoxControl::HandleBoundVirtual //

/*private */Void SFZListBoxControl::Relocate(Void)
{
    SFXRectangle                                rc(GetLocalBound());

    if (_bar != null) {
        rc.Deflate(GetBoxMargin());
        rc.SubRight(_barWidth);
        _bar->SetRealBound(SFXRectangle(rc.GetRight(), rc.GetTop(), _barWidth, rc.GetHeight()));
    }
    return;
}// SFZListBoxControl::Relocate //

Reference

SFYResponder::SetRealBound | SFYResponder::SetVirtualBound | Region Event[SFEVT_RESPONDER_BOUND] | Handler for the Region Event[XANDLER_DECLARE_VOIDBOUND] | Virtual Region | Real Region | Local Region

Description

This function will be called when the SFEVT_KEY event(key event[SFEVT_KEY]) of the ESCAPE key set with the SFZListBoxControl::SetEscapeKey function is received.

In case you want to perform your own processing, override this function.

The default implementation is to send the result event[SFXEvent(SFEVT_RESPONDER_RESULT, SFP16_RESULT_ESCAPE, 0)].

Internal Implementation

Internal implementation of the SFZListBoxControl::HandleEscapeKey function is as follows:

/*protected virtual */Void SFZListBoxControl::HandleEscapeKey(Void)
{
    InvokeForward(SFXEvent(SFEVT_RESPONDER_RESULT, SFP16_RESULT_ESCAPE, 0), false);
    return;
}// SFZListBoxControl::HandleEscapeKey //

Reference

SFZListBoxControl::SetEscapeKey | SFXEvent | Result Event[SFEVT_RESPONDER_RESULT] | Key Event[SFEVT_KEY]

Description

This function will be called when the SFEVT_KEY event(key event[SFEVT_KEY]) of the operaion key set with the SFYBoxControl::SetOperateKey function is received.

In case you want to perform your own processing, override this function.

The default implementation is as follows:

Internal Implementation

Internal implementation of the SFZListBoxControl::HandleOperateKey function is as follows:

struct ListItem {
    SFXWideString                       text;
    AVKType                             key;
    WChar                               keyIcon;
    SFXRGBColor                         foreColor;
    SFXRGBColor                         backColor;
    Bool                                enable;
};

/*protected virtual */Void SFZListBoxControl::HandleOperateKey(Void)
{
    ListItemPtr                                 item;

    if ((item = GetListItem(GetCurrentValue())) != null) {
        if (item->enable) {
            InvokeForward(SFXEvent(SFEVT_RESPONDER_RESULT, SFP16_RESULT_OK, GetCurrentValue()), false);
        }
    }
    return;
}// SFZListBoxControl::HandleOperateKey //

Reference

SFYBoxControl::SetOperateKey | SFZListBoxControl::SetItemEnable | SFXEvent | Result Event[SFEVT_RESPONDER_RESULT] | Key Event[SFEVT_KEY]

Description

This function will be called when the (SFEVT_RESPONDER_RENDER, SFP16_RENDER_REQUEST) event is received.

In case you want to perform your own drawing of this responder, override this function.

The default implementation is to draw this responder.

The method to darw a responder

In addition to overriding this virtual function, it is possible to define and implement the handler for drawing event(drawing handler)[XANDLER_DECLARE_VOIDRENDER], and register it into the responder. Then, the overridden virtual function will be called first, and next the drawing handlers registered into the responder will be booted up in the registered order. In almost all cases, the method to override this function is used to draw the responder since there is no need to declare and register the drawing handler.

Procedure of drawing a responder

The drawing handler will be booted up when the drawing event(SFEVT_RESPONDER_RENDER) occurs. And then the drawing handler draw the responder actually. The drawing event will be sent to only the responders including the region to be redrawn out of the redraw regions registered into the renderer using the SFYResponder::InvokeBackward function after the SFYResponder::Render function boots up the renderer. Here, the SFYResponder::Render function will be called at the following situations: At the end of the event loop At the applet start / resume or the end of a highest priority event handler In the callback, which is outside the event loop. If calling the SFYResponder::Render function with specifying "true" as an argument, the drawing event will be sent to all the responders to be actually displayed on the screen which are located below the responder in the responder tree, regardless of the registration of redraw region.

Internal Implementation

Internal implementation of the SFZListBoxControl::HandleRenderRequest function is as follows:

struct ListItem {
    SFXWideString                       text;
    AVKType                             key;
    WChar                               keyIcon;
    SFXRGBColor                         foreColor;
    SFXRGBColor                         backColor;
    Bool                                enable;
};

/*protected virtual */Void SFZListBoxControl::HandleRenderRequest(SFXGraphicsPtr graphics) const
{
    SFXRectangle                                rc(GetLocalBound());

    DrawBox(graphics, rc);
    DrawItemList(graphics, rc.Deflate(GetBoxMargin()));
    return;
}// SFZListBoxControl::HandleRenderRequest //

/*private */Void SFZListBoxControl::DrawItemList(SFXGraphicsPtr graphics, SFXRectangleConstRef rectangle) const
{
    SFXRectangle                                rc(rectangle);
    SInt16                                      itemHeight(GetItemHeight());

    if (_bar != null && _bar->GetStateVisible()) {
        rc.SubRight(_barWidth);
    }
    if (rc.GetHeight() > itemHeight) {
        rc.SetHeight(itemHeight);
    }
    for (SInt32 i = 0; i < GetFieldValue(); ++i) {
        if (GetTopValue() + i < GetItemCount()) {
            DrawItem(graphics, rc, i + GetTopValue());
            if (_line) {
                graphics->DrawLine(rc.GetEdgeBottom(), _color.gridLine);
            }
        }
        rc.AddY(itemHeight);
    }
    return;
}// SFZListBoxControl::DrawItemList //

/*private */Void SFZListBoxControl::DrawItem(SFXGraphicsPtr graphics, SFXRectangleConstRef rectangle, SInt32 index) const
{
    ListItemPtr                                 item;
    SFXRectangle                                rc(rectangle);
    SFXGrid                                     grid;
    SFXRGBColor                                 fore;
    SFXRGBColor                                 back;

    if ((item = GetListItem(index)) != null) {
        fore.Set(item->foreColor);
        back.Set(item->backColor);
        if (!item->enable || !GetStateActive(true)) {
            (fore.GetBrightness() > 0x7F) ? fore.SubRGB(RGB_ACTIVE) : fore.AddRGB(RGB_ACTIVE);
        }
        else if (index == GetCurrentValue()) {
            fore.Set(_color.selFore);
        }
        if (!item->enable) {
            (back.GetBrightness() > 0x7F) ? back.SubRGB(RGB_ENABLE) : back.AddRGB(RGB_ENABLE);
        }
        if (index == GetCurrentValue()) {
            back.Set(_color.selBack);
        }
        graphics->FillRectangle(rectangle, back);
        rc.Deflate(GetListMargin());
        if (item->keyIcon != 0) {
     SFXRectangle iconRect(rc);
            iconRect.SetSize(GetFontSize());
            graphics->SetFont(_font);
            graphics->DrawSingleText(SFXWideString(item->keyIcon), iconRect, fore, IDF_ALIGN_LEFT);
            rc.AddX(iconRect.GetWidth());
        }
        grid = rc.GetOrigin();
        if (index == GetCurrentValue()) {
            grid.AddX(_offset);
        }
        graphics->SetFont(_font);
        graphics->DrawSingleText(item->text, grid, rc, fore, IDF_ALIGN_LEFT);
    }
    return;
}// SFZListBoxControl::DrawItem //

/*private */inline SFXSize SFZListBoxControl::GetFontSize(Void) const
{
    return _size;
}// SFZListBoxControl::GetFontSize //

Reference

SFYResponder::Invalidate | SFYResponder::Render | SFYResponder::InvokeBackward | Drawing Event[SFEVT_RESPONDER_RENDER] | Handler for the Drawing Event[XANDLER_DECLARE_VOIDRENDER] | Rendering | Event Loop | Responder Tree | Virtual Region | Real Region | Local Region

Return value

Description

This function inserts the specified item before the specified index.

If the value of the specified index is less than or equals 0, the item will be inserted at the head.

If the value of the specified index is greater than or equals the maximum value, the item will be inserted at the tail.

	Note
	The numuber of items can be obtained by calling the SFZListBoxControl::GetItemCount function.

Reference

SFZListBoxControl::InsertFirst | SFZListBoxControl::InsertLast | SFZListBoxControl::Remove | SFZListBoxControl::GetItemCount

Return value

Description

This function inserts the specified item at the head.

	Note
	The numuber of items can be obtained by calling the SFZListBoxControl::GetItemCount function.

Reference

SFZListBoxControl::Insert | SFZListBoxControl::InsertLast| SFZListBoxControl::RemoveFirst | SFZListBoxControl::GetItemCount

Return value

Description

This function inserts the specified item at the tail.

	Note
	The numuber of items can be obtained by calling the SFZListBoxControl::GetItemCount function.

Reference

SFZListBoxControl::Insert | SFZListBoxControl::InsertFirst | SFZListBoxControl::RemoveLast | SFZListBoxControl::GetItemCount

Argument

Return value

Description

This function creates a new instance of this responder class.

If succeeds, a not null pointer will be returned, and the "exception" argument is SFERR_NO_ERROR. If fails such as insufficient memory, a null pointer will be returned, and the "exception" argument holds the error value.

Example

The code to create a new instance of this responder class is as follows:

SFZListBoxControlSmp _listbox;
SFCError error;

if ((_listbox = SFZListBoxControl::NewInstance(&error)) != null) {

    ...
}

Description

This function removes the item at the specified index or the items in the specified index range from this list box control.

If the specified index is less than 0 or greater than or equals the number of items, no item will be removed

If the beginning index to remove is greater than or equals the number of items or the ending index to remove is less than or equals 0, no item will be removed

If the beginning index to remove is less than or equals 0, it will be reset to 0.

If the ending index to remove is greater than the number of items, it will be reset to the number of items.

	Note
	The numuber of items can be obtained by calling the SFZListBoxControl::GetItemCount function.

Reference

SFZListBoxControl::Clear SFZListBoxControl::RemoveFirst | SFZListBoxControl::RemoveLast | SFZListBoxControl::Insert | SFZListBoxControl::GetItemCount

Description

This function removes the first item from this list box control.

	Note
	The numuber of items can be obtained by calling the SFZListBoxControl::GetItemCount function.

Reference

SFZListBoxControl::Clear | SFZListBoxControl::Remove | SFZListBoxControl::RemoveLast | SFZListBoxControl::InsertFirst | SFZListBoxControl::GetItemCount

Description

This function removes the last item from this list box control.

	Note
	The numuber of items can be obtained by calling the SFZListBoxControl::GetItemCount function.

Reference

SFZListBoxControl::Clear | SFZListBoxControl::Remove | SFZListBoxControl::RemoveFirst | SFZListBoxControl::InsertLast | SFZListBoxControl::GetItemCount

Description

This function sets the default background color(SFXRGBColor) of unselected item of this list box control to the specified value.

Default: SFXRGBColor(0xFF, 0xFF, 0xFF, 0x00)[white color]

Default background color of unselected item

The default background color of unselected item can be changed using the SFZListBoxControl::SetItemBackColor function. If you want to make the background color of unselected item be the same one, the background color needs to be set using this function. The SFZListBoxControl::SetItemBackColor function to set it individually is not recommended. However, the background color of selected item is always the one set with the SFZListBoxControl::SetSelBackColor function.

Reference

SFZListBoxControl::GetDefaultItemBackColor | SFZListBoxControl::SetDefaultItemForeColor | SFZListBoxControl::SetItemBackColor | SFZListBoxControl::SetSelBackColor | SFZListBoxControl::SetItemEnable | SFXRGBColor::GetBrightness | SFXRGBColor

Description

This function sets the default foreground color(SFXRGBColor) to draw the text of unselected item of this list box control to the specified value.

Default: SFXRGBColor(0x00, 0x00, 0x00, 0x00)[black color]

Default foreground color of unselected item

The default foreground color of unselected item can be changed using the SFZListBoxControl::SetItemForeColor function. If you want to make the foreground color of all unselected items be the same one, the foreground color needs to be set using this function. The SFZListBoxControl::SetItemForeColor function to set it individually is not recommended. However, the foreground color of selected item is always the one set with the SFZListBoxControl::SetSelForeColor function, except when the enable flag of item is set to "false" using the SFZListBoxControl::SetItemEnable function.

Foreground color of unselected item when the enable flag of the item is set to "false" or in the "inactive" state

If the enable flag of item is set to "false" using the SFZListBoxControl::SetItemEnable function or this list box control is in the "inactive" state, the text will not be drawn in the foreground color set with this function. In this case, the foreground color will be the color subtracted 0x33 from each RGB value of the color set with this function if the brightness of color is bigger than 0x7F, otherwise it will be the color added 0x33 on each RGB value of the color. The brightness of color is the value obtained using the SFXRGBColor::GetBrightness function.

Reference

SFZListBoxControl::GetDefaultItemForeColor | SFZListBoxControl::SetDefaultItemBackColor | SFZListBoxControl::SetItemForeColor | SFZListBoxControl::SetSelForeColor | SFZListBoxControl::SetItemEnable | SFXRGBColor::GetBrightness | SFXRGBColor | State

Return value

*** description of return value ***

Description

This function sets the DOWN key of this list box control to the specified value.

Default: AVK_DOWN.

If the DOWN key is pressed, the internal handler(*) of this list box control will move the selected item down by one item and send the value event.

When "true" is set to the "repeat-scroll" flag using the SFZListBoxControl::SetScrollRepeat and the bottom item is currently selected, the top item will be selected if the DOWN key is pressed.

On the contrary, when "false" is set to the "repeat-scroll" flag and the bottom item is currently selected, the bottom item will be still selected even if the DOWN key is pressed.

	Internal handler
	The value event of SFXEvent(SFEVT_RESPONDER_VALUE, SFP16_VALUE_CURRENT, index of selected item) will be sent by the internal handler of this list box control when the DOWN key is pressed.

Reference

SFZListBoxControl::GetDownKey | SFZListBoxControl::GetUpKey | SFZListBoxControl::SetUpKey | SFZListBoxControl::SetScrollRepeat | SFXEvent | Value Event[SFEVT_RESPONDER_VALUE]

Description

This function sets the ESCAPE key of this list box control to the specified value.

Default: AVK_CLR

The SFZListBoxControl::HandleEscapeKey function will be called if the ESCAPE key is pressed.

Reference

SFZListBoxControl::GetEscapeKey | SFZListBoxControl::HandleEscapeKey

Description

This function sets the font to the specified value , which is for the item text of this list box control.

Default: AEE_FONT_NORMAL.

Reference

SFZListBoxControl::GetFont

Description

This function sets the color(SFXRGBColor) of grid line of this list box control to the specified value.

The grid line will be drawn in the color set with this function only if its enable flag is set to "true" using the SFZListBoxControl::SetGridLineEnable function.

Default: SFXRGBColor(0x00, 0x00, 0x00, 0x00)[black color].

	Drawing region of the grid line
	The grid line will be drawn in the bottom line of 1 pixel width within the rectangular region of each item. It is recommended to set the margin region for the grid line using the SFZListBoxControl::SetListMargin function in case this enable flag is set to "true".

Reference

SFZListBoxControl::GetGridLineColor | SFZListBoxControl::SetGridLineEnable | SFXRGBColor

Description

This function sets the enable flag of the grid line of this list box control to the specified value.

The grid line will be drawn in the color set with the SFZListBoxControl::SetGridLineColor function only if its enable flag is set to "true" using this function.

Default: false.

	Drawing region of the grid line
	The grid line will be drawn in the bottom line of 1 pixel width within the rectangular region of each item. It is recommended to set the margin region for the grid line using the SFZListBoxControl::SetListMargin function in case this enable flag is set to "true".

Reference

SFZListBoxControl::GetGridLineEnable | SFZListBoxControl::SetGridLineColor | SFZListBoxControl::SetListMargin

Description

This function sets the access key and the key icon of the specified item of this list box control to specified values.

When the enable flag of item is set to "true" using the SFZListBoxControl::SetItemEnable function, the SFZListBoxControl::HandleAccessKey function will be called if the access key set with this function is pressed.

Example

The code below shows how to set a access key and a key icon for an item.

// set access key to AVK_1, key icon to 0xFBF6 for first list item of _list list box 
_listbox->SetItemAccessKey(0, AVK_1, 0xFBF6);

Reference

SFZListBoxControl::GetItemAccessKey | SFZListBoxControl::HandleAccessKey | SFZListBoxControl::SetItemEnable

Description

This function sets the background color(SFXRGBColor) of the specified item of this list box when unselected to the specified value.

Default: The default background color set with the SFZListBoxControl::SetDefaultItemBackColor function. SFXRGBColor(0xFF, 0xFF, 0xFF, 0x00)[white color] if the default background color is not set.

When "false" is set to the enable flag using the SFZListBoxControl::SetItemEnable function, the background will not be filled in the color set with this function.

In this case, the background will be drawn in the color of which each RGB value is subtracted 0x33 from the color set with this function if the brightness of this color is greater than 0x7F. Otherwise it will be drawn in the color of which each RGB value is added 0x33 on the color set with this function.

The brightness of color can be obtained by calling the SFXRGBColor::GetBrightness function.

	Foreground color of unselected item
	For the foreground color of unselected item, refer to SFZListBoxControl::SetItemForeColor.

	Foreground color of selected item
	For the foreground color of selected item, refer to SFZListBoxControl::SetSelForeColor.

	Background color of selected item
	For the background color of selected item, refer to SFZListBoxControl::SetSelBackColor.

Example

*** Example ***

Reference

SFZListBoxControl::SetDefaultItemBackColor | SFZListBoxControl::GetItemBackColor | SFZListBoxControl::SetItemForeColor | SFZListBoxControl::SetItemEnable | SFXRGBColor::GetBrightness | SFZListBoxControl::SetSelForeColor | SFZListBoxControl::SetSelBackColor | SFXRGBColor

Description

This function sets the enable flag of the specified item of this list box control to the specified value.

Default: "true"(The item is valid.)

When the enable flag of an item is set to "false"

Even if the operation key or the access key is pressed, the result event will not be sent. The foreground color will be the color subtracted 0x44 from each RGB value of the item foreground color set with the SFZListBoxControl::SetItemForeColor function if the brightness of item foreground color is bigger than 0x7F, otherwise it will be the color added 0x44 on each RGB value of the item foreground color. The background color will be the color subtracted 0x33 from each RGB value of the item background color set with the SFZListBoxControl::SetItemBackColor function if the brightness of item background color is bigger than 0x7F, otherwise it will be the color added 0x33 on each RGB value of the item background color. The brightness of color is the value obtained using the SFXRGBColor::GetBrightness function.

	Note
	If the enable flag of item is set to "false", the text of item will be drawn in the above adjusted foreground color when selected. It will not be drawn in the color set with the SFZListBoxControl::SetSelForeColor function. The background of item is drawn in the color set with the SFZListBoxControl::SetSelBackColor function when selected, regardless of the value of enable flag of item.

Reference

SFZListBoxControl::GetItemEnable | SFZListBoxControl::HandleOperateKey | SFZListBoxControl::HandleAccessKey | SFZListBoxControl::SetItemForeColor | SFZListBoxControl::SetItemBackColor | SFZListBoxControl::SetSelForeColor | SFZListBoxControl::SetSelBackColor | SFZListBoxControl::SetSelForeColor

Description

This function sets the foreground color(SFXRGBColor) to draw the text of the specified unselected item of this list box control to the specified value.

Default: The default foreground color set with the SFZListBoxControl::SetDefaultItemForeColor function. SFXRGBColor(0x00, 0x00, 0x00, 0x00)[black color] if the default background color is not set.

Foreground color of unselected item when the enable flag of item is set to "false" or in the "inactive" state

If the enable flag of item is set to "false" using the SFZListBoxControl::SetItemEnable function or this list box control is in the "inactive" state, the text will not be drawn in the foreground color set with this function. In this case, the foreground color will be the color subtracted 0x33 from each RGB value of the color set with this function if the brightness of color is bigger than 0x7F, otherwise it will be the color added 0x33 on each RGB value of the color. The brightness of color is the value obtained using the SFXRGBColor::GetBrightness function.

	Background color of unselected item
	For the background color of unselected item, refer to SFZListBoxControl::SetItemBackColor.

	Background color of unselected item
	For the background color of unselected item, refer to SFZListBoxControl::SetItemBackColor.

	Foreground color of selected item
	For the foreground color of selected item, refer to SFZListBoxControl::SetSelForeColor.

	Background color of selected item
	For the background color of selected item, refer to SFZListBoxControl::SetSelBackColor.

Reference

SFZListBoxControl::SetDefaultItemForeColor | SFZListBoxControl::GetItemForeColor | SFZListBoxControl::SetItemBackColor | SFZListBoxControl::SetSelForeColor | SFZListBoxControl::SetSelBackColor | SFZListBoxControl::SetItemEnable | SFXRGBColor::GetBrightness | SFXRGBColor | State

Description

This function sets the key icon of the specified item of this list box control to the specified value.

Example

The code below shows how to set a key icon for an item.

// set key icon to 0xFBF6 for first list item of _list list box 
_listbox->SetItemKeyIcon(0, 0xFBF6);

Reference

SFZListBoxControl::GetItemKeyIcon

Description

This function sets the text of the specified item of this list box control to the specified value.

Reference

SFZListBoxControl::GetItemText

Description

This function sets the margin within each item of this list box control to the specified value.

The contents of each item are drawn within the item region excluding this margin sepecified with this function.

Default: SFXMargin(1, 2)

Reference

SFZListBoxControl::GetListMargin | SFXMargin

Description

This function sets the scroll bar control used by the list box control to the specified value.

The developer can set his or her own scroll bar control to the list box control.

Example

The code below is to set the custom scroll bar control to the list box control.

// define class of original scroll bar control
class CustomScrollBarControl : public SFYScrollBarControl {
    // definition
};

Void UserApplication::SomeFunction {
    SFZListBoxControlSmp        list;
    CustomScrollBarControlSmp   bar;

    // create list box control
    list = SFZListBoxControl::NewInstance();

    // settings of list box control
    // …

    // create scroll bar control
    bar = CustomScrollBarControl::NewInstance();

    // set original scroll bar to list box control
    list->SetScrollBarControl(bar);
    return;
}

Reference

SFYScrollBarControl SFZListBoxControl::GetScrollBarControl

Description

This function sets the width of the scroll bar control to the specified value, which this list box control contains internally.

Default: SFZListBoxControl::DEFAULT_BAR_WIDTH

For the value of SFZListBoxControl::DEFAULT_BAR_WIDTH, refer to SFZListBoxControl::DefaultEnum.

Reference

SFZListBoxControl::GetScrollBarWidth | SFZListBoxControl::DefaultEnum

Description

This function sets the scroll direction to the specified value.

Default: SFZListBoxControl::DEFAULT_DIRECTION

For the value of SFZListBoxControl::DEFAULT_DIRECTION, refer to SFZListBoxControl::DirectionEnum.

Reference

SFZListBoxControl::GetScrollDirection | SFZListBoxControl::DirectionEnum

Description

Default: SFZListBoxControl::DEFAULT_SCROLL [milliseconds]

For the value of SFZListBoxControl::DEFAULT_SCROLL, refer to SFZListBoxControl::DefaultEnum.

Reference

SFZListBoxControl::GetScrollInterval | SFZListBoxControl::DirectionEnum

Description

This function sets the repeat-scroll flag of this list box control to the specified value.

When the repeat-scroll flag is set to "true" and the top item or the bottom item is currently selected item, the bottom item or the top item will be currently selected item if the UP key or DOWM key is pressed, respectively.

When the repeat-scroll flag is set to "false" and the top item or the bottom item is currently selected item, the top item or the bottom item will be still currently selected item even if the UP key or DOWM key is pressed, respectively.

	About the UP key and the DOWM key
	The UP key or DOWM key is set with the SFZListBoxControl::SetUpKey function or SFZListBoxControl::SetDownKey function respectively.

Reference

SFZListBoxControl::GetScrollRepeat | SFZListBoxControl::SetUpKey | SFZListBoxControl::SetDownKey

Description

This function sets the number of pixels of each scroll. [pixels]

If "-1"(this is default value) is set, the scroll-step will be set to the width of the " " character of the currently used font.

Default: SFZListBoxControl::DEFAULT_STEP [pixels]

For the value of SFZListBoxControl::DEFAULT_STEP, refer to SFZListBoxControl::DefaultEnum.

Reference

SFZListBoxControl::GetScrollStep | SFZListBoxControl::DirectionEnum

Description

This function sets the background color(SFXRGBColor) of currently selected item of this list box control to the specified value, in which the rectangle containing the selected item is filled.

Default: SFXRGBColor(0x11, 0x22, 0xBB, 0x00)[blue color]

	Foreground color of selected item
	For the foreground color of selected item, refer to SFZListBoxControl::SetSelForeColor.

	Foreground color of unselected item
	For the foreground color of unselected item, refer to SFZListBoxControl::SetItemForeColor.

	Background color of unselected item
	For the background color of unselected item, refer to SFZListBoxControl::SetItemBackColor.

Reference

SFZListBoxControl::GetSelBackColor | SFZListBoxControl::GetSelForeColor | SFZListBoxControl::SetSelForeColor | SFZListBoxControl::SetItemBackColor | SFZListBoxControl::SetItemForeColor | SFXRGBColor

Description

This function sets the foreground color(SFXRGBColor) to draw the text of the specified selected item of this list box control to the specified value.

Default: SFXRGBColor(0xFF, 0xFF, 0xFF, 0x00)[white color]

If the enable flag of an item is set to "false" using the SFZListBoxControl::SetItemEnable function or this list box control is in the "inactive" state, the text will not be drawn in the foreground color set with this function.

In this case, the foreground color will be the color subtracted 0x33 from each RGB value of the color set with this function if the brightness of color is bigger than 0x7F, otherwise it will be the color added 0x33 on each RGB value of the color.

The brightness of color is the value obtained using the SFXRGBColor::GetBrightness function.

	Background color of selected item
	For the background color of selected item, refer to SFZListBoxControl::SetSelBackColor.

	Foreground color of unselected item
	For the foreground color of unselected item, refer to SFZListBoxControl::SetItemForeColor.

	Background color of unselected item
	For the background color of unselected item, refer to SFZListBoxControl::SetItemBackColor.

Reference

SFZListBoxControl::GetSelForeColor | SFZListBoxControl::SetSelBackColor | SFZListBoxControl::SetItemForeColor | SFZListBoxControl::SetItemBackColor | SFZListBoxControl::SetItemEnable | SFXRGBColor::GetBrightness | SFXRGBColor | State

Description

This function sets the UP key of the list box control to the specified value.

Default: AVK_UP.

If the UP key is pressed, the internal handler(*) of this list box control will move the selected item up by one item and send the value event.

When the repeat-scroll flag is set to "true" using the SFZListBoxControl::SetScrollRepeat and the top item is currently selected, the bottom item will be selected if the UP key is pressed.

On the contrary, when the repeat-scroll flag is set to "false" and the top item is currently selected, the top item will be still selected even if the UP key is pressed.

	Internal handler
	The value event of SFXEvent(SFEVT_RESPONDER_VALUE, SFP16_VALUE_CURRENT, index of selected item) will be sent by the internal handler of this list box control when the UP key is pressed.

Reference

SFZListBoxControl::GetUpKey | SFZListBoxControl::GetDownKey | SFZListBoxControl::SetDownKey SFZListBoxControl::SetScrollRepeat | SFXEvent | Value Event[SFEVT_RESPONDER_VALUE]

Description

This function sets the waiting time to start the scroll to the specified value. [milliseconds]

Default: SFZListBoxControl::DEFAULT_SCROLL [milliseconds]

For the value of SFZListBoxControl::DEFAULT_SCROLL, refer to SFZListBoxControl::DefaultEnum.

Reference

SFZListBoxControl::SetWaitInterval | SFZListBoxControl::DirectionEnum