=for comment based on iup-3.9 - http://www.tecgraf.puc-rio.br/iup/en/ctrl/iupmatrixlist.html

=head1 NAME

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

=head1 DESCRIPTION

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

It uses the matrix columns to display labels, color boxes and check
boxes in a way that is not possible using L<IUP::List|IUP::List>. But the control
mimics the L<IUP::List|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.

=begin HTML

<p>
  <table border="1">
    <tbody align="center">
      <tr>
        <td><img src="http://kmx.github.io/perl-iup/img-3.9/ctrl/iupmatrixlist1.png"></td>
        <td><img src="http://kmx.github.io/perl-iup/img-3.9/ctrl/iupmatrixlist2.png"></td>
      </tr>
    </tbody>
  </table>
</p>

=end HTML

=head1 USAGE

=head2 CREATION - new() method

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

B<Returns:> the identifier of the created element, or C<undef> if an error occurs.

NOTE: You can pass to C<new()> other C<ATTRIBUTE=E<gt>'value'> or C<CALLBACKNAME=E<gt>\&func> pairs relevant
to this element - see L<IUP::Manual::02_Elements|IUP::Manual::02_Elements/"new()">.

=head2 ATTRIBUTES

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

=over

=item B<"1">

First item in the list.

=item B<"2">

Second item in the list.

=item B<"3">

Third item in the list.

=item B<< "<n>" >>

n-h item in the list.

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

=item B<ADDLIN>

I<(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 "B<I<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.

=item B<APPENDITEM>

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

=item B<COLORCOL>

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

=item B<COLORI(id)>

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

=item B<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).

=item B<COUNT>

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

=item B<DELLIN>

I<(write-only)> removes the given line from the list. To remove
more than one line, use format "B<I<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.

=item B<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.

=item B<FOCUSCOLOR>

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

=item B<FOCUSITEM>

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

=item B<IMAGEI(id)>

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

=item B<IMAGEACTIVEI(id)>

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

=item B<IMAGEADD>

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

Use image name or L<IUP::Image> reference. See - L<Using Images in Other Elements (via IMAGE Attribute)|IUP::Image/"Using Images in Other Elements (via IMAGE Attribute)">.

Image column must be available.

=item B<IMAGECHECK>

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

Use image name or L<IUP::Image> reference. See - L<Using Images in Other Elements (via IMAGE Attribute)|IUP::Image/"Using Images in Other Elements (via IMAGE Attribute)">.

Image column must be available.

=item B<IMAGECOL>

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

=item B<IMAGEDEL>

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

Use image name or L<IUP::Image> reference. See - L<Using Images in Other Elements (via IMAGE Attribute)|IUP::Image/"Using Images in Other Elements (via IMAGE Attribute)">.

Image column must be available.

=item B<IMAGEUNCHECK>

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

Use image name or L<IUP::Image> reference. See - L<Using Images in Other Elements (via IMAGE Attribute)|IUP::Image/"Using Images in Other Elements (via IMAGE Attribute)">.

Image column must be available.

=item B<IMAGEVALUEI(id)>

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

=item B<INSERTITEMI(id)>

I<(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.

=item B<ITEMACTIVEI(id)>

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

=item B<ITEMFGCOLORI(id)>

text color of an item (id).

=item B<ITEMBGCOLORI(id)>

background color of an item (id).

=item B<LABELCOL >(read-only)

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

=item B<REMOVEITEM >(write-only)

removes the given item from the list.

=item B<SHOWDELETE>

Shows only the B<IMAGEDEL> image and ignores B<IMAGECHECK> and B<IMAGEUNCHECK>.

=item B<TITLE>

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

=item B<TOPITEM>

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

=item B<VALUE>

defines or retrieves the value of the current cell.

=item B<VISIBLELINES>

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

=back

B<Other Attributes:>

Since the L<IUP::MatrixList|IUP::MatrixList> inherits its implementation from 
the L<IUP::Matrix|IUP::Matrix>, and that one from L<IUP::Canvas|IUP::Canvas>,
those controls attributes and callbacks can be used. But notice that L<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:

=over

=item B<EXPAND>: changed to "NO"

=item B<ALIGNMENTLIN0>: changed to "ALEFT"

=item B<CURSOR>: changed to "ARROW"

=item B<FRAMETITLEHIGHLIGHT>: changed to "NO"

=item B<HIDEFOCUS>: changed to "YES"

=item B<SCROLLBAR>: changed to "VERTICAL"

=back

The following L<common attributes|IUP::Manual::03_Attributes/Common Attributes> are also accepted:

=over

=item * L<ACTIVE|IUP::Manual::03_Attributes/ACTIVE>,
L<EXPAND|IUP::Manual::03_Attributes/EXPAND>,
L<FONT|IUP::Manual::03_Attributes/FONT>,
L<SCREENPOSITION|IUP::Manual::03_Attributes/SCREENPOSITION>,
L<POSITION|IUP::Manual::03_Attributes/POSITION>,
L<MINSIZE|IUP::Manual::03_Attributes/MINSIZE>,
L<MAXSIZE|IUP::Manual::03_Attributes/MAXSIZE>,
L<WID|IUP::Manual::03_Attributes/WID>,
L<TIP|IUP::Manual::03_Attributes/TIP>,
L<SIZE|IUP::Manual::03_Attributes/SIZE>,
L<RASTERSIZE|IUP::Manual::03_Attributes/RASTERSIZE>,
L<ZORDER|IUP::Manual::03_Attributes/ZORDER>,
L<VISIBLE|IUP::Manual::03_Attributes/VISIBLE>

=back

=head2 CALLBACKS

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

=over

=item B<IMAGEVALUECHANGED_CB>

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

B<Callback handler prototype:>

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

B<$self:> identifier of the element that activated the event.

B<$lin:> item line.

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

=item B<LISTACTION_CB>

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

B<Callback handler prototype:>

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

B<$self:> identifier of the element that activated the event.

B<$item:> Number of the changed item starting at 1.

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

=item B<LISTCLICK_CB>

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

B<Callback handler prototype:>

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

B<$self:> identifier of the element that activated the event.

B<$lin:> item line.

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

B<$status:> Status of the mouse buttons and some keyboard keys at the
moment the event is generated. The same macros used for L<BUTTON_CB|IUP::Manual::04_Callbacks/BUTTON_CB> can be used for this status.

B<Returns:> To avoid the default processing return IUP_IGNORE.

=item B<LISTDRAW_CB>

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

B<Callback handler prototype:>

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

B<$self:> identifier of the element that activated the event.

B<$lin:> item line.

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

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

B<$canvas:> internal canvas CD used to draw the list.

B<Returns:> If IUP_IGNORE the normal drawing will take place.

=item B<LISTEDITION_CB>

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

B<Callback handler prototype:>

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

B<$self:> identifier of the element that activated the event.

B<$lin:> item line.

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

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

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

=item B<LISTINSERT_CB>

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

B<Callback handler prototype:>

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

B<$self:> identifier of the element that activated the event.

B<$lin:> position of the new item.

=item B<LISTRELEASE_CB>

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

B<Callback handler prototype:>

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

B<$self:> identifier of the element that activated the event.

B<$lin:> item line.

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

B<$status:> Status of the mouse buttons and some keyboard keys at the
moment the event is generated. The same macros used for L<BUTTON_CB|IUP::Manual::04_Callbacks/BUTTON_CB> can be used for this status.

B<Returns:> To avoid the default processing return IUP_IGNORE.

=item B<LISTREMOVE_CB>

Action generated when an item is removed of the list.

B<Callback handler prototype:>

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

B<$self:> identifier of the element that activated the event.

B<$lin:> position of the removed item.

=back 
  
=head1 EXAMPLES


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

=over

=item * L<0-basic/matrixlist.pl|https://metacpan.org/source/KMX/IUP-0.303/examples/0-basic/matrixlist.pl> - IUP::MatrixList example

=back 



=head1 SEE ALSO

L<IUP::Canvas|IUP::Canvas>, L<IUP::Matrix|IUP::Matrix>

The original doc: L<iupmatrixlist.html|http://www.tecgraf.puc-rio.br/iup/en/ctrl/iupmatrixlist.html>
 

=cut