/ 
IUP-0.304
River stage zero No dependents
/ IUP::MatrixList

NAME

IUP::MatrixList - [GUI element] displays a list of items with labels, images/icons, color boxes and check boxes

DESCRIPTION

Creates an interface element that displays a list of items, just like IUP::List, but internally uses a IUP::Matrix.

It uses the matrix columns to display labels, color boxes and check boxes in a way that is not possible using IUP::List. But the control mimics the IUP::List attributes, callbacks and interaction, so the usage by the programmer and by the user should be very similar.

Based on MTXLIB, developed at Tecgraf/PUC-Rio by Renata Trautmann and Andre Derraik.

USAGE

CREATION - new() method

$mlist = IUP::MatrixList->new( 1=>"line 1", 2=>"line 2", 3=>"line 3" );

Returns: the identifier of the created element, or undef if an error occurs.

NOTE: You can pass to new() other ATTRIBUTE=>'value' or CALLBACKNAME=>\&func pairs relevant to this element - see IUP::Manual::02_Elements.

ATTRIBUTES

For more info about concept of attributes (setting/getting values etc.) see IUP::Manual::03_Attributes. Attributes specific to this element:

"1"

First item in the list.

"2"

Second item in the list.

"3"

Third item in the list.

"<n>"

n-h item in the list.

(non inheritable) Item value. It can be any text. Differently from the IUP::List control, the item must exist so its label can be changed. So APPENDITEM, INSERTITEMid , ADDLIN or COUNT attributes must be used to reserve space for the list items. Notice that lines and items in the list are the same thing.

ADDLIN

(write-only) adds a new line to the list after the specified line. To insert a line at the top, value 0 must be used. To add more than one line, use format "L-L", where the first number corresponds to the base line and the second number corresponds to the number of lines to be added. Ignored if set before map.

APPENDITEM

(write-only) inserts an item after the last item. Ignored if set before map.

COLORCOL

(read-only) returns the number of color column. If not exists, returns 0.

COLORI(id)

the color displayed at the color column. If not defined the color box is not diplayed.

COLUMNORDER

defines or retrieves the display order of the columns. Possible values a combination of: "LABEL", "COLOR" and "IMAGE". These values also can be combined in these formats: VALUE1 (one column); VALUE1:VALUE2 (two columns) or VALUE1:VALUE2:VALUE3 (three columns). Default: "LABEL" (one column).

COUNT

defines the number of items in the list. Differently from the IUP::List control it is not read-only.

DELLIN

(write-only) removes the given line from the list. To remove more than one line, use format "L-L", where the first number corresponds to the base line and the second number corresponds to the number of lines to be removed. Ignored if set before map.

EDITABLE

enables the interactive editing of the list. It can be Yes or No. Default: "NO". An empty item at the end of the list will be available so new items can be interactively inserted. Also while editing a label, the IMAGE column will display a button so the item can be interactively removed.

FOCUSCOLOR

the background color when an item get the focus. Values in RGB format ("r g b"). Default: "255 235 155".

FOCUSITEM

defines the current focus item.Default: "1".

IMAGEI(id)

(write-only) name of the image to be used in the specified item (id). Use IUP::SetHandle or =item * IUP::SetAttributeHandle to associate an image to a name. See also IUP::Image. Image column must be available.

IMAGEACTIVEI(id)

controls the interaction with the image of an item. It can be Yes or No. Default: Yes. Image column must be available.

IMAGEADD

(write-only) name of the image that will be shown when the IUP::MatrixList is editable. Default: "MTXLIST_IMG_ADD".

Use image name or IUP::Image reference. See - Using Images in Other Elements (via IMAGE Attribute).

Image column must be available.

IMAGECHECK

(write-only) name of the image that will be shown when the IMAGEVALUE attribute is "IMAGECHECK". Default: "MTXLIST_IMG_CHECK".

Use image name or IUP::Image reference. See - Using Images in Other Elements (via IMAGE Attribute).

Image column must be available.

IMAGECOL

(read-only) returns the number of image column. If not exists, returns 0.

IMAGEDEL

(write-only) name of the image that will be shown when the IUP::MatrixList is editable or when SHOWDELETE=Yes. Default: "MTXLIST_IMG_DEL".

Use image name or IUP::Image reference. See - Using Images in Other Elements (via IMAGE Attribute).

Image column must be available.

IMAGEUNCHECK

(write-only) name of the image that will be shown when the IMAGEVALUE attribute is "IMAGEUNCHECK". Default: "MTXLIST_IMG_UNCHECK".

Use image name or IUP::Image reference. See - Using Images in Other Elements (via IMAGE Attribute).

Image column must be available.

IMAGEVALUEI(id)

selects the CHECK or the UNCHECK image to display for an item (id). It can be Yes or No. Default: NO.

INSERTITEMI(id)

(write-only) inserts an item before the given id position (id starts at 1). If id=COUNT+1 then it will append after the last item. Ignored if out of bounds. Ignored if set before map.

ITEMACTIVEI(id)

controls the interaction with an item (id). It can be Yes or No. Default: "YES".

ITEMFGCOLORI(id)

text color of an item (id).

ITEMBGCOLORI(id)

background color of an item (id).

LABELCOL (read-only)

returns the number of label column. If not exists, returns 0.

REMOVEITEM (write-only)

removes the given item from the list.

SHOWDELETE

Shows only the IMAGEDEL image and ignores IMAGECHECK and IMAGEUNCHECK.

TITLE

title of the list. When not undef the list will display a non scrollable title.

TOPITEM

(write-only) position the given item at the top of the list or near to make it visible.

VALUE

defines or retrieves the value of the current cell.

VISIBLELINES

defines the number of visible lines for the Natural Size, this means that will act also as minimum number of visible lines. Default "3".

Other Attributes:

Since the IUP::MatrixList inherits its implementation from the IUP::Matrix, and that one from IUP::Canvas, those controls attributes and callbacks can be used. But notice that IUP::MatrixList uses several of them internally for its own purpose, and reusing them may affect the control behavior and appearance.

Some attribute defaults were changed:

EXPAND: changed to "NO"
ALIGNMENTLIN0: changed to "ALEFT"
CURSOR: changed to "ARROW"
FRAMETITLEHIGHLIGHT: changed to "NO"
HIDEFOCUS: changed to "YES"
SCROLLBAR: changed to "VERTICAL"

The following common attributes are also accepted:

CALLBACKS

For more info about concept of callbacks (setting callback handlers etc.) see IUP::Manual::04_Callbacks. Callbacks specific to this element:

IMAGEVALUECHANGED_CB

called after the image value was interactively changed by the user (mark/unmark).

Callback handler prototype:

sub imagevaluechanged_cb_handler {
  my ($self, $lin, $imagevalue) = @_;
  #...
}

$self: identifier of the element that activated the event.

$lin: item line.

$imagevalue: equal to 1 if the image used was IMAGECHECK or to 0 if the image used IMAGEUNCHECK.

LISTACTION_CB

Action generated when the state of an item in the list is changed. Also provides information on the changed item:

Callback handler prototype:

sub listaction_cb_handler {
  my ($self, $item, $state) = @_;
  #...
}

$self: identifier of the element that activated the event.

$item: Number of the changed item starting at 1.

$state: Equal to 1 if the option was selected or to 0 if the option was deselected.

LISTCLICK_CB

Action generated when any mouse button is pressed over a item.

Callback handler prototype:

sub listclick_cb_handler {
  my ($self, $lin, $col, $status) = @_;
  #...
}

$self: identifier of the element that activated the event.

$lin: item line.

$col: item column (label, image or color).

$status: Status of the mouse buttons and some keyboard keys at the moment the event is generated. The same macros used for BUTTON_CB can be used for this status.

Returns: To avoid the default processing return IUP_IGNORE.

LISTDRAW_CB

Action generated when an item needs to be redrawn. It is called before the default processing.

Callback handler prototype:

sub listdraw_cb_handler {
  my ($self, $lin, $col, $x1, $x2, $y1, $y2, $canvas) = @_;
  #...
}

$self: identifier of the element that activated the event.

$lin: item line.

$col: item column (label, image or color).

$x1, $x2, $y1, $y2: bounding rectangle of the current cell in pixels, excluding the decorations.

$canvas: internal canvas CD used to draw the list.

Returns: If IUP_IGNORE the normal drawing will take place.

LISTEDITION_CB

Action generated when the current cell of an item enters or leaves the edition mode. Called before the default processing.

Callback handler prototype:

sub listedition_cb_handler {
  my ($self, $lin, $col, $mode, $update) = @_;
  #...
}

$self: identifier of the element that activated the event.

$lin: item line.

$col: item column (label, image or color).

$mode: equal to 1 if the cell has entered the edition mode, or 0 if the cell has left the edition mode.

$update: equal to 1 to redraw, or 0 to no update returning IUP_IGNORE.

LISTINSERT_CB

Action generated when a new item is inserted into the list.

Callback handler prototype:

sub listinsert_cb_handler {
  my ($self, $lin) = @_;
  #...
}

$self: identifier of the element that activated the event.

$lin: position of the new item.

LISTRELEASE_CB

Action generated when any mouse button is released over a item.

Callback handler prototype:

sub listrelease_cb_handler {
  my ($self, $lin, $col, $status) = @_;
  #...
}

$self: identifier of the element that activated the event.

$lin: item line.

$col: item column (label, image or color).

$status: Status of the mouse buttons and some keyboard keys at the moment the event is generated. The same macros used for BUTTON_CB can be used for this status.

Returns: To avoid the default processing return IUP_IGNORE.

LISTREMOVE_CB

Action generated when an item is removed of the list.

Callback handler prototype:

sub listremove_cb_handler {
  my ($self, $lin) = @_;
  #...
}

$self: identifier of the element that activated the event.

$lin: position of the removed item.

EXAMPLES

The element IUP::MatrixList is used in the following sample scripts:

SEE ALSO

IUP::Canvas, IUP::Matrix

The original doc: iupmatrixlist.html