IUP::MatrixList - [GUI element] displays a list of items with labels, images/icons, color boxes and check boxes
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.
$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.
undef
NOTE: You can pass to new() other ATTRIBUTE=>'value' or CALLBACKNAME=>\&func pairs relevant to this element - see IUP::Manual::02_Elements.
new()
ATTRIBUTE=>'value'
CALLBACKNAME=>\&func
For more info about concept of attributes (setting/getting values etc.) see IUP::Manual::03_Attributes. Attributes specific to this element:
First item in the list.
Second item in the list.
Third item in the list.
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.
(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.
(write-only) inserts an item after the last item. Ignored if set before map.
(read-only) returns the number of color column. If not exists, returns 0.
the color displayed at the color column. If not defined the color box is not diplayed.
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).
defines the number of items in the list. Differently from the IUP::List control it is not read-only.
(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.
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.
the background color when an item get the focus. Values in RGB format ("r g b"). Default: "255 235 155".
defines the current focus item.Default: "1".
(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.
controls the interaction with the image of an item. It can be Yes or No. Default: Yes. Image column must be available.
(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.
(write-only) name of the image that will be shown when the IMAGEVALUE attribute is "IMAGECHECK". Default: "MTXLIST_IMG_CHECK".
(read-only) returns the number of image column. If not exists, returns 0.
(write-only) name of the image that will be shown when the IUP::MatrixList is editable or when SHOWDELETE=Yes. Default: "MTXLIST_IMG_DEL".
(write-only) name of the image that will be shown when the IMAGEVALUE attribute is "IMAGEUNCHECK". Default: "MTXLIST_IMG_UNCHECK".
selects the CHECK or the UNCHECK image to display for an item (id). It can be Yes or No. Default: NO.
(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.
controls the interaction with an item (id). It can be Yes or No. Default: "YES".
text color of an item (id).
background color of an item (id).
returns the number of label column. If not exists, returns 0.
removes the given item from the list.
Shows only the IMAGEDEL image and ignores IMAGECHECK and IMAGEUNCHECK.
title of the list. When not undef the list will display a non scrollable title.
(write-only) position the given item at the top of the list or near to make it visible.
defines or retrieves the value of the current cell.
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:
The following common attributes are also accepted:
ACTIVE, EXPAND, FONT, SCREENPOSITION, POSITION, MINSIZE, MAXSIZE, WID, TIP, SIZE, RASTERSIZE, ZORDER, VISIBLE
For more info about concept of callbacks (setting callback handlers etc.) see IUP::Manual::04_Callbacks. Callbacks specific to this element:
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.
Action generated when the state of an item in the list is changed. Also provides information on the changed item:
sub listaction_cb_handler { my ($self, $item, $state) = @_; #... }
$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.
Action generated when any mouse button is pressed over a item.
sub listclick_cb_handler { my ($self, $lin, $col, $status) = @_; #... }
$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.
Action generated when an item needs to be redrawn. It is called before the default processing.
sub listdraw_cb_handler { my ($self, $lin, $col, $x1, $x2, $y1, $y2, $canvas) = @_; #... }
$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.
Action generated when the current cell of an item enters or leaves the edition mode. Called before the default processing.
sub listedition_cb_handler { my ($self, $lin, $col, $mode, $update) = @_; #... }
$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.
Action generated when a new item is inserted into the list.
sub listinsert_cb_handler { my ($self, $lin) = @_; #... }
$lin: position of the new item.
Action generated when any mouse button is released over a item.
sub listrelease_cb_handler { my ($self, $lin, $col, $status) = @_; #... }
Action generated when an item is removed of the list.
sub listremove_cb_handler { my ($self, $lin) = @_; #... }
$lin: position of the removed item.
The element IUP::MatrixList is used in the following sample scripts:
0-basic/matrixlist.pl - IUP::MatrixList example
IUP::Canvas, IUP::Matrix
The original doc: iupmatrixlist.html
To install IUP, copy and paste the appropriate command in to your terminal.
cpanm
cpanm IUP
CPAN shell
perl -MCPAN -e shell install IUP
For more information on module installation, please visit the detailed CPAN module installation guide.