wxRuby Documentation Home

# Wx::VListBox

VListBox is a control with multiple items like
listbox. It has two major differences: it can have an
arbitrarily huge number of items because it doesn’t store them itself
but uses an on_draw_item method to draw them (so
it is a *V*irtual listbox), and its items can have variable height as
determined by on_measure_item (so it is also a
listbox with the lines of *V*ariable height).

To use this class, you must inherit from it and create your own subclass
in Ruby. It doesn’t have any methods to append or insert items. Instead
you just have to call set_item_count to tell
the control how many items it should display. Your subclass must define
the methods on_measure_item, to tell the GUI
how tall a given item is, and on_draw_item, which
should accept a DC which is used to draw each element in the
list.

It emits the same events as ListBox and the same event
handler methods may be used with it.

## Derived from

VScrolledWindow

## Methods

- VListBox.new
- VListBox#clear
- VListBox#deselect_all
- VListBox#get_item_count
- VListBox#get_margins
- VListBox#get_selected_count
- VListBox#get_selection
- VListBox#get_selections
- VListBox#get_selection_background
- VListBox#has_multiple_selection
- VListBox#is_current
- VListBox#is_selected
- VListBox#on_draw_background
- VListBox#on_draw_item
- VListBox#on_draw_separator
- VListBox#on_measure_item
- VListBox#select
- VListBox#select_all
- VListBox#select_range
- VListBox#set_item_count
- VListBox#set_margins
- VListBox#set_selection
- VListBox#set_selection_background
- VListBox#toggle

### VListBox.new

VListBox.new(%(arg-type)Window% parent, Integer id = ID_ANY, Point pos = DEFAULT_POSITION, Size size = DEFAULT_SIZE, Integer countItems = 0, Integer style = 0, String name = “VListBox”)

Normal constructor. The only special style which may be used with
VListBox is `LB_MULTIPLE` which indicates that the listbox should
support multiple selection.

### VListBox#clear

clear()

Deletes all items from the control.

### VListBox#deselect_all

Boolean deselect_all()

Deselects all the items in the listbox. Returns `true` if any items were
changed, i.e. if there had been any selected items before, or `false` if
all the items were already deselected.

This method is only valid for multi selection listboxes.

#### See also

select_all, Select

### VListBox#get_item_count

Integer get_item_count()

Get the number of items in the control.

#### See also

set_item_count

### VListBox#get_margins

Point get_margins()

Returns the margins used by the control. The `x` field of the returned
point is the horizontal margin and the `y` field is the vertical one.

#### See also

set_margins

### VListBox#get_selected_count

Integer get_selected_count()

Returns the number of the items currently selected.

It is valid for both single and multi selection controls. In the former case it
may only return $0$ or $1$ however.

#### See also

is_selected,

get_first_selected,

get_next_selected

### VListBox#get_selection

Integer get_selection()

Get the currently selected item or `-1` if there is no selection.

### VListBox#get_selections

Array get_selections()

For list boxes supporting multiple selection only, returns an array with
the integer indices of all the selected items.

### VListBox#get_selection_background

Colour get_selection_background()

Returns the background colour used for the selected cells. By default the
standard system colour is used.

#### See also

SystemSettings#get_colour,

set_selection_background

### VListBox#has_multiple_selection

Boolean has_multiple_selection()

Returns `true` if the listbox was created with `LB_MULTIPLE` style
and so supports multiple selection or `false` if it is a single selection
listbox.

### VListBox#is_current

Boolean is_current(%(arg-type)Integer% item)

Returns `true` if this item is the current one, `false` otherwise.

Current item is always the same as selected one for the single selection
listbox and in this case this method is equivalent to
is_selected but they are different for multi
selection listboxes where many items may be selected but only one (at most) is
current.

### VListBox#is_selected

Boolean is_selected(%(arg-type)Integer% item)

Returns `true` if this item is selected, `false` otherwise.

### VListBox#on_draw_background

on_draw_background(%(arg-type)DC% dc, Rect rect, Integer n)

This method is used to draw the items background and, maybe, a border
around it.

The base class version implements a reasonable default behaviour which
consists in drawing the selected item with the standard background
colour and drawing a border around the item if it is either selected or
current.

### VListBox#on_draw_item

on_draw_item(%(arg-type)DC% dc, Rect rect, Integer n)

The ruby subclass must implement this function to actually draw the item
with the given index on the provided DC. Note that the origin
co-ordinates of the DC are relative to the top-left corner of the whole
control, not of the individual item. So to draw elements such as text
within each item correctly, when you call DC drawing methods, you should
add the y value of the rect to the y value
representing where within the individual item the text or other drawing
should appear.

#### Parameters

- dc The device context to use for drawing
- rect The bounding rectangle for the item being drawn (DC clipping
  region is set to this rectangle before calling this function)
- n The index of the item to be drawn

### VListBox#on_draw_separator

on_draw_separator(%(arg-type)DC% dc, Rect rect, Integer n)

This method may be used to draw separators between the lines. The rectangle
passed to it may be modified, typically to deflate it a bit before passing to
on_draw_item.

The base class version of this method doesn’t do anything.

#### Parameters

- dc The device context to use for drawing
- rect The bounding rectangle for the item
- n The index of the item

### VListBox#on_measure_item

Integer on_measure_item(%(arg-type)Integer% n)

The derived class must implement this method to return the height of the
specified item (in pixels).

### VListBox#select

Boolean select(%(arg-type)Integer% item, Boolean select = true)

Selects or deselects the specified item which must be valid (i.e. not
equal to `NOT_FOUND`).

Return `true` if the items selection status has changed or `false`
otherwise.

This function is only valid for the multiple selection listboxes, use
set_selection for the single selection ones.

### VListBox#select_all

Boolean select_all()

Selects all the items in the listbox.

Returns `true` if any items were changed, i.e. if there had been any
unselected items before, or `false` if all the items were already selected.

This method is only valid for multi selection listboxes.

#### See also

deselect_all, Select

### VListBox#select_range

Boolean select_range(%(arg-type)Integer% from, Integer to)

Selects all items in the specified range which may be given in any order.

Return `true` if the items selection status has changed or `false`
otherwise.

This method is only valid for multi selection listboxes.

#### See also
p
select_all, Select

### VListBox#set_item_count

set_item_count(%(arg-type)Integer% count)

Set the number of items to be shown in the control.

This is just a synonym for
VScrolledWindow::set_line_count.

### VListBox#set_margins

set_margins(%(arg-type)Point% pt) set_margins(%(arg-type)Integer% x, Integer y)

Set the margins: horizontal margin is the distance between the window
border and the item contents while vertical margin is half of the
distance between items.

By default both margins are `0`.

### VListBox#set_selection

set_selection(%(arg-type)Integer% selection)

Set the selection to the specified item, if it is $-1$ the selection is
unset. The selected item will be automatically scrolled into view if it isn’t
currently visible.

This method may be used both with single and multiple selection listboxes.

### VListBox#set_selection_background

set_selection_background(%(arg-type)Colour% col)

Sets the colour to be used for the selected cells background. The background of
the standard cells may be changed by simply calling
set_background_colour.

#### See also

get_selection_background

### VListBox#toggle

toggle(%(arg-type)Integer% item)

Toggles the state of the specified item, i.e. selects it if it was
unselected and deselects it if it was selected. This method is only
valid for multi selection listboxes.

#### See also

Select

[This page automatically generated from the Textile source at 2023-06-09 00:45:37 +0000]