class MASKING_DLL_DECLSPEC ListBoxEx

The ListBoxEx widget.

Inheritance:

ListBoxEx - ScrollBox - CompoundWidget - Dialog - Widget - Rect

Public Methods

virtual void SetHeader(Header* header)

Sets a custom header object.

virtual Header* GetHeader()

Returns a pointer to the header object.

virtual int InsertColumn(const char* titleText, int index=-1, int align=0, int colWidth=-1)

Adds a new column to the listbox.

virtual void DeleteColumn(int index)

Deletes the specified column

virtual int GetColumnCount()

Returns the number of columns in the listbox

virtual void SetColumnTitle(int index, const char* title)

Sets the title for the specified column

virtual const char* GetColumnTitle(int index)

Retreives the title of the specified column

virtual void SetColumnWidth(int index, int width)

Sets the width of the specified column.

virtual int GetColumnWidth(int index)

Retreives the width of the specified column.

virtual int InsertItem(Item* item, int index=-1)

Adds a new item to the list.

virtual int InsertItem(const char* item, int index=-1)

Adds an item with the specified text in the first column

virtual void DeleteItem(int index)

Removes the specified item from the list

virtual void DeleteAllItems()

Clears the list of all items

virtual void SetItem(int row, int column, const char* str)

Shortcut for setting the text at the specified row and column.

virtual const char* GetItem(int row, int col)

Retreives the text at the specified row and column.

virtual Item* GetItem(int row)

Retreives the item at the specified row.

virtual int GetItemCount()

Returns number of items (rows) in the list

virtual bool ScrollToItem(int index, bool force=false)

Scrolls the listbox if necessary so that the item with the specified index becomes visible.

virtual void SetHeaderVisibility(bool on)

Overrides the automatically determined header visibility status.

virtual bool GetHeaderVisibility()

Returns user's header visibility setting

virtual void EnableMultiSelect(bool on=true)

Enables or disables multiselect mode.

virtual bool IsMultiSelectEnabled()

Returns the value of the multiSelect variable

virtual int GetSelectedCount()

Counts the number of selected items

virtual bool IsSelected(int index)

Returns true if the specified item is selected, false otherwise.

virtual void Select(int index)

Selects the item at the specified index.

virtual void Deselect(int index)

Deselects the item at the specified index if it is not deselected already.

virtual Item* GetSelectedItem()

Returns a pointer to the selected item.

virtual int GetSelectedIndex()

Returns the index of the selected item.

virtual int GetMouseRowIndex()

Returns the index of the item (row) the mouse cursor is on top of.

virtual int GetMouseColumnIndex()

Returns the index of the item (column) the mouse cursor is on top of.

virtual void Toggle(int index)

Toggles the state of the specified item.

virtual void DeselectAllItems()

Deselects all previously selected items.

virtual int GetFirstSelectedIndex()

Returns the index of the first selected item or -1 if no items are selected

virtual int GetNextSelectedIndex()

Returns the next selected item or -1 if no more items are selected.

virtual void EnableSingleClick(bool on=true)

Sets the value of the singleClick variable

virtual bool IsSingleClickEnabled()

Gets the value of the singleClick variable

virtual void Sort(int column=0, int order=1)

Sorts the list.

virtual void EnableAutosort(bool on=true)

Enables or disables automatic list sorting.

bool IsAutosortEnabled()

Returns the status of autosorting

void EnableColumnResizing(bool on=true)

Enables or disables column resizing

bool IsColumnResizingEnabled()

Checks whether column resizing is enabled or not

void EnableGridLines(bool on=true)

Turns gridlines between cells of the list on or off

bool AreGridLinesEnabled()

Checks whether gridlines are turned on or off

void HandleEvent(Widget &obj, int msg, int arg1=0, int arg2=0)

Event handler.

Public Members

class MASKING_DLL_DECLSPEC Column

Represents one column item.

class MASKING_DLL_DECLSPEC Header: public Button

The listbox header widget.

class MASKING_DLL_DECLSPEC Item

Represent one listbox item (one row of values)

class MASKING_DLL_DECLSPEC InputHandler: public Widget

Invisible helper widget the listbox uses for getting input (keyboard, mouse).

Protected Fields

std::vector<Column> columns

the array of column headers

Header* header

Pointer to a header widget used for renering column headers.

Header ownHeader

The listbox's own default header widget.

std::vector<Item *> items

The array of listbox items.

InputHandler inputHandler

The invisible input helper widget

int focusedItem

The index of the item the mouse is currently hovering over.

int selectedItem

The currently selected item.

bool showHeader

True if header should be shown, false otherwise.

bool multiSelect

True if the list is in multiselect mode, false otherwise.

bool singleClick

Defines how many clicks are necessary to activate an item.

int iterationIndex

Temporary variable used for iterating through the selected items of the list with GetFirstSelectedIndex() and GetNextSelectedIndex()

bool autoSort

True if clicking on a header column should sort the list, false otherwise.

bool columnResizing

True if column resizing is enabled, false otherwise.

bool gridLines

True if gridlines should be drawn between cells of the listbox.

Protected Methods

void UpdateSize()

Called after every change in listbox geometry to update the size and position of the headers widget and the fake input handler

void DrawClientArea(Bitmap &dest, int xofst, int yofst)

Draws the contents of the listbox (ie.

virtual void UpdateScrollers()

Called on every geometry change as well as every time the contents of the listbox have been modified (ie.

virtual void OnMousemove()

Called on every mouse move.

virtual void OnChar(int c)

Called on every key press while the list has input.

virtual void OnLPress()

Called whenever the left mouse button is clicked on the list.

virtual void OnWheel(int z)

Called on every mouse wheel scroll event while the list has input focus.

virtual void OnDClick()

Called when an item is double clicked.

Documentation

The ListBoxEx widget. A ListBoxEx is a widget for displaying lists of items. It provides many modes of operation. By default it behaves like a plain single column list box like the one found in the default Allegro GUI. But it can also accept an arbitrary number of column that can be interactively resized. It can behave as a normal single select list where only one item at a time is selected, or as a multi select list where any number of items can be selected. Column headers can be forcefully turned off if required. Clicking a column header automatically sorts the list lexicographically according to the selected column. Both the item and the header classes can be easily extended to support custom look, feel and behaviour.

ListBoxEx sends MSG_SCROLL to the parent dialog whenever the selection changes with the index of the selected item as the first argument to the HandleEvent() function. When an item is double clicked (or single clicked if the single click option is turned on), or the enter or space keys are pressed, MSG_ACTIVATE is sent with the index of the item that was activated as the first argument. MSG_ACTIVATE can be overridden with a custom message with the Wiget::SetCallback() function.

std::vector<Column> columns

the array of column headers

Header* header

Pointer to a header widget used for renering column headers. Users may override this with their own custom header widget (for example one that draws some fancy icons or something) which is the reason why a pointer is stored.

Header ownHeader

The listbox's own default header widget. Used by default in case the user doesn't supply their own header object (i.e. almost always).

std::vector<Item *> items

The array of listbox items. Pointers are used because the users may derive their own special item classes from the default one to implement some custome behaviour.

InputHandler inputHandler

The invisible input helper widget

int focusedItem

The index of the item the mouse is currently hovering over. This is also used when browsing the listbox with the keyboard. In single select mode the focused item is always immediately selected.

int selectedItem

The currently selected item. Only relevant in single select mode.

bool showHeader

True if header should be shown, false otherwise. This is determined automatically from the list contents, but can be overridden by the user. Lists with one column and no column title automatically hide the header, in all other cases the header is automatically turned on.

bool multiSelect

True if the list is in multiselect mode, false otherwise. When in multiselect mode any item can be selected or deselected independantly of all other items. In single select mode exactly one items is always selected (except when the list is empty of course). Default is false.

bool singleClick

Defines how many clicks are necessary to activate an item. If true, one click activates, otherwise a double click is required. The first is useful for drop down lists while the other is usually better for normal lists. The default is false.

int iterationIndex

Temporary variable used for iterating through the selected items of the list with GetFirstSelectedIndex() and GetNextSelectedIndex()

bool autoSort

True if clicking on a header column should sort the list, false otherwise. Default is false.

bool columnResizing

True if column resizing is enabled, false otherwise. Default is true.

bool gridLines

True if gridlines should be drawn between cells of the listbox. Default is false.

void UpdateSize()

Called after every change in listbox geometry to update the size and position of the headers widget and the fake input handler

void DrawClientArea(Bitmap &dest, int xofst, int yofst)

Draws the contents of the listbox (ie. the list items) with the current scroll offset.

virtual void UpdateScrollers()

Called on every geometry change as well as every time the contents of the listbox have been modified (ie. items or columns added or removed) to update the scrollers.

virtual void OnMousemove()

Called on every mouse move. Handles changing focus item on mouse moves.

virtual void OnChar(int c)

Called on every key press while the list has input. Handles switching focus and/or selection between items and activates items on enter or space. Overload this to implement some custom behaviour, like for example a listbox that allows editing of the items or something similar.

virtual void OnLPress()

Called whenever the left mouse button is clicked on the list. Handles changing item selection status with the mouse.

virtual void OnWheel(int z)

Called on every mouse wheel scroll event while the list has input focus. Handles scrolling the list with the mouse wheel.

virtual void OnDClick()

Called when an item is double clicked. Handles item activation on double clicks in case single click mode is not enabled.

virtual void SetHeader(Header* header)

Sets a custom header object. If you derive a custom header class from Header, create a new instance and pass the pointer to it to this function. The listbox then owns this object so you must not attempt to delete it yourself, it will be done automatically for you.

See Also:

Header

virtual Header* GetHeader()

Returns a pointer to the header object. Useful for manipulating custom headers. You probably shouldn't call any methods the Header inherits from the button class otherwise logic and appearance of the listbox might get messed up. Typically you will only need to call this function to opbtain a pointer to a custom header object, so you can for example feed it some additional data.

See Also:

Header

virtual int InsertColumn(const char* titleText, int index=-1, int align=0, int colWidth=-1)

Adds a new column to the listbox.

Parameters:

titleText - the column title
index - the position where you want to add the new column; if negative the column will be added to the end of the column list
align - alignment of the column title: 0 is left, 1 is right and 2 is centre alignment
colWidth - width of the column; if -1 the most appropriate width will be calculated automatically

Returns:

Index of the position where the column was actually added or -1 on failure (e.g. invalid index).

virtual void DeleteColumn(int index)

Deletes the specified column

virtual int GetColumnCount()

Returns the number of columns in the listbox

virtual void SetColumnTitle(int index, const char* title)

Sets the title for the specified column

virtual const char* GetColumnTitle(int index)

Retreives the title of the specified column

virtual void SetColumnWidth(int index, int width)

Sets the width of the specified column. Width may be -1 to allow the listbox to determine the actual width of the item automatically.

virtual int GetColumnWidth(int index)

Retreives the width of the specified column. Returns -1 if the index is invalid.

virtual int InsertItem(Item* item, int index=-1)

Adds a new item to the list. The item is added at the specified index or at the end of the list if index is a negative number. After adding an item, the listbox owns it, so you must not attempt to delete it.

Note: If a column hadn't been added to the listbox yet, one will be created automatically.

Returns:

The index of item where it was actually added to the list or -1 on failure.

See Also:

Item

virtual int InsertItem(const char* item, int index=-1)

Adds an item with the specified text in the first column

virtual void DeleteItem(int index)

Removes the specified item from the list

virtual void DeleteAllItems()

Clears the list of all items

virtual void SetItem(int row, int column, const char* str)

Shortcut for setting the text at the specified row and column. If the specified column doesn't exist yet, enough columns are added to the list so that this function may succeed.

Parameters:

row - index of the item you want to change
column - index of the column you want to change
str - the new item text

virtual const char* GetItem(int row, int col)

Retreives the text at the specified row and column. Returns NULL if the given coordinates are invalid.

virtual Item* GetItem(int row)

Retreives the item at the specified row. Returns NULL if the row is invalid.

virtual int GetItemCount()

Returns number of items (rows) in the list

virtual bool ScrollToItem(int index, bool force=false)

Scrolls the listbox if necessary so that the item with the specified index becomes visible. If force is true, the function scrolls regardless of the previous status, else it scrolls only if necessary. Returns true if any scrolling was actually done, otherwise returns false.

virtual void SetHeaderVisibility(bool on)

Overrides the automatically determined header visibility status. Pass false to turn the heaer off on multicolumn lists.

virtual bool GetHeaderVisibility()

Returns user's header visibility setting

virtual void EnableMultiSelect(bool on=true)

Enables or disables multiselect mode. If multiselect mode is turned off while more than one item is selected, all items are deselected except for the first one that was selected. If none were selected, the first one is selected after calling this function.

virtual bool IsMultiSelectEnabled()

Returns the value of the multiSelect variable

virtual int GetSelectedCount()

Counts the number of selected items

virtual bool IsSelected(int index)

Returns true if the specified item is selected, false otherwise. If index is invalid, returns false.

virtual void Select(int index)

Selects the item at the specified index. In single select mode the previously selected item is deselected.

virtual void Deselect(int index)

Deselects the item at the specified index if it is not deselected already. In single select mode, this function does nothing.

virtual Item* GetSelectedItem()

Returns a pointer to the selected item. In multiselect mode the first selected item is returned, or NULL if no items are selected.

virtual int GetSelectedIndex()

Returns the index of the selected item. This function is equivalent to GetFirstSelectedIndex().

virtual int GetMouseRowIndex()

Returns the index of the item (row) the mouse cursor is on top of. Returns -1 if the mouse is not top of a list item.

virtual int GetMouseColumnIndex()

Returns the index of the item (column) the mouse cursor is on top of. Returns -1 if the mouse is not top of a list item.

virtual void Toggle(int index)

Toggles the state of the specified item. In multiselect mode selects the item at the specified index if it was previously not selected or deselects it if it was. Has no meaning in single select mode.

virtual void DeselectAllItems()

Deselects all previously selected items. Only relevant in multiselect mode.

virtual int GetFirstSelectedIndex()

Returns the index of the first selected item or -1 if no items are selected

virtual int GetNextSelectedIndex()

Returns the next selected item or -1 if no more items are selected. This function is used to iterate through the selected items of the list. To initialize the iteration first call GetFirstSelectedIndex() then this function until it returns -1.

virtual void EnableSingleClick(bool on=true)

Sets the value of the singleClick variable

virtual bool IsSingleClickEnabled()

Gets the value of the singleClick variable

virtual void Sort(int column=0, int order=1)

Sorts the list. The list is sorted in either ascending or descending order according to the specified column and order.

Parameters:

column - The index of the column used for sorting.
order - Order of sorting. Positive values (typically 1) select ascending order, negative values (typically -1) select descending order. Sorting requires being able to compare items. For that the less than operator of the Item class is used. The default implementation sorts the items lexicographically. To implement custom sorting (e.g. by numerical values, dates, etc) simply overload the less than operator in your custom item class.

See Also:

Item

virtual void EnableAutosort(bool on=true)

Enables or disables automatic list sorting. When automatic sorting is on, the list is automatically sorted when a column header is clicked. Explicitely calling Sort() still sorts the list even when autosorting is disabled. By default autosorting is disabled.

bool IsAutosortEnabled()

Returns the status of autosorting

void EnableColumnResizing(bool on=true)

Enables or disables column resizing

bool IsColumnResizingEnabled()

Checks whether column resizing is enabled or not

void EnableGridLines(bool on=true)

Turns gridlines between cells of the list on or off

bool AreGridLinesEnabled()

Checks whether gridlines are turned on or off

void HandleEvent(Widget &obj, int msg, int arg1=0, int arg2=0)

Event handler. Basicalyl jsut maps messages from the input handler to the OnSomething() functions.

This class has no child classes.

Friends:

class ListBoxEx::Item

Alphabetic index Hierarchy of classes