Reference » Window classes » MListBox

Elgrint::MListBox class

Declared in WCListBox.h

Description

Lets the user select one or more items from a linear list, displayed within the window.
Read more...

MListBox

Base class: MScrollBar

Properties:

Name Description
ItemHeight The height of each item in the list (in pixels).
MultiSelect If true, more than one item can be selected at once, otherwise - one at most.
ReselectOnKey If true, the existing selection is cancelled if the user presses any navigation key.
RevealObscured If true, a partially obscured item is revealed using MInfoLabel when the cursor is on top of the item.

Initializers:

Name Description
MListBox(parent,rect,nidSelected,names,icons) Standard-form constructor. Creates and opens a new list box window.

Mutators:

Name Description
deselect(first,last) Deselects all items from first to last (inclusive), if selected.
insert(atIndex,name,icon) Inserts a single item at atIndex with the specified name and icon.
insert(atIndex,names,icons) Inserts multiple items starting at atIndex with the specified names and icons.
remove(first,last) Removes all items from first to last (inclusive).
select(first,last,replace) Selects all items from first to last (inclusive).
setFocusItem(atIndex) Marks the specified item as the focused (current) item.
setItemIcon(atIndex,newIcon) Changes the icon of the specified item.
setItemName(atIndex,newName) Changes the name of the specified item.
toggle(first,last) Changes the selection state of each item from first to last (inclusive) to its opposite.

Revealers:

Name Description
getFocusItem() Returns the 0-based index of the current (focused) item (see setFocusItem), even if the window is closed.
getItemAt(pos,checkBounds) Returns the index of an item at the specified position (in window coordinates).
getItemCount() Returns the total number of items in the list (even if the window is closed).
getItemIcon(atIndex) Returns the icon, associated with the specified item (even if the window is closed).
getItemIconRect(index) Returns the bounding rectangle of the specified item's icon (in window coordinates).
getItemName(atIndex) Returns the name of the specified item (even if the window is closed).
getItemNameRect(index) Returns the bounding rectangle of the specified item's name (in window coordinates).
getItemRect(atIndex) Returns the bounding rectangle of the specified item (in window coordinates).
getSelection() Returns the 0-based indices of all the selected items (even if the window is closed).
getSelectionCount() Returns the total number of the currently selected items (even if the window is closed).
getVisibleItemsRange() Returns 0-based indices of the first and last items, which are currently displayed in the window.
isSelected(index) Returns true iff the item at index is selected (even if the window is closed).

Handlers:

Name Description
OnCursorMoved

Track selection with cursor, reveal obscured item using MInfoLabel.

OnFocusChanged

Stop tracking and selection with the Shift+arrow, repaint.

OnHotChanged

Allow the info label that reveals partially obscured items (see RevealObscured) to reappear.

OnKeysEntered

Navigation, selection change, end tracking

OnPaint

Draw items, selection marks, and focus mark

OnTimerExpired

Autoscroll during track selection

Details

Much like MTreeListBox and MMenuBox, the list box contains a vertically stacked list of items, each of which can contain an icon, a text, or both, except that here the items cannot be expanded – only selected. Therefore, there are no multi-level items in the list box, and each item is identified by a numerical zero-based index, starting from the top.

Like MTreeListBox, the list box is derived from MScrollBar, so it could fit a lot of items, if necessary, and like the tree-list it supports an automatic MInfoLabel child to reveal partially obscure items, unless RevealObscured property is false.

However, MListBox differs from other lists by letting the user select many items at the same time, not just one of them as in tree-list box and menu box. Thus, getSelection returns not a single value, but a vector of numbers (MVector<MNum>), each of which is equal to the 0-based index of one of the currently selected items. That being said, if the MultiSelect property is false (which is a default value, actually), then no more than one item can be selected, though getSelection still returns a vector, which can contain 0 or 1 elements.

One of the items (but only one, regardless of MultiSelect setting) can also be a focus item. The focus and selected states of an item are independent of each other, yet closely connected (see below). The focus item is marked by a dashed outline around the item.

The user can focus and/or select an item by clicking it or by using navigation keys. If ReselectOnKey property is false, then navigation keys only change the focus item, not selection, otherwise they change both at the same time and deselect any existing selection at the same time. Either way, once an item is focused, its selected state can be toggled with the space key. Ctrl+click combination can also toggle the selection of an item. If MultiSelect is false, then each new selection automatically deselects the existing one. If MultiSelect is true, then multiple items can be selected by cursor tracking (clicking one item and then moving the cursor without releasing the click), or by Ctrl+A (select all) and Ctrl+I (select inverse) keys. The items' states can also be changed programmatically, using select, deselect, toggle, and setFocusItem functions, but all these functions are still subject to the limitation, specified by MultiSelect. Any change in selection generates the "Selected" Notice, and any change in the focus item's position generates "FocusItemChanged" Notice.

The list content is defined using insert, setItemName, setItemIcon, and remove functions. All these operations generate a "ContentChanged" Notice.

The remaining MListBox functions allow some additional customization or used internally for list box operation and painting.

Example

Let us know

Please Contact us to report any errors on this page, or to suggest any improvements.

Miranor Home | About Miranor | About Elgrint | Create account | Login | Account settings | Contact Us | Privacy Policy | Site map

© Copyright 2014 by Miranor. All rights reserved. By using this site you agree to the Terms of Use.

Page last updated on August 10th, 2014.