NAME

IUP::Cells - [GUI element] grid widget (set of cells) that enables chess-table-like drawings

DESCRIPTION

Creates a grid widget (set of cells) that enables several application-specific drawing, such as: chess tables, tiles editors, degrade scales, drawable spreadsheets and so forth.

This element is mostly based on application callbacks functions that determine the number of cells (rows and coluns), their appearence and interation. This mechanism offers full flexibility to applications, but requires programmers attention to avoid infinite loops inside this functions. Using callbacks, cells can be also grouped to form major or hierarchical elements, such as headers, footers etc. This callback approach was intentionally chosen to allow all cells to be dinamically and directly changed based on application's data structures. Since the size of each cell is given by the application the size of the control also must be given using SIZE or RASTERSIZE attributes.

Checkerboard Pattern	Numbering Cells

USAGE

CREATION - new() method

my $cells = IUP::Cells->new( BOXED=>'NO', RASTERSIZE=>'400x300' );

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:

BOXED

Determines if the bounding cells' regions should be drawn with black lines. It can be "YES" or "NO". Default: "YES". If the span atributtes are used, set this attribute to "NO" to avoid grid drawing over spanned cells.

BUFFERIZE

Disables the automatic redrawing of the control, so many attributes can be changed without many redraws. When set to "NO" the control is redrawn. When REPAINT attribute is set, BUFFERIZE is automatically set to "NO". Default: "NO".

CANVAS

(read-only, non inheritable)

Returns the internal CD canvas (reference to IUP::Canvas). ZZZ-test-this This attribute should be used only in specific cases and by experienced programmers.

CLIPPED

Determines if, before cells drawing, each bounding region should be clipped. This attribute should the changed in few specific cases. It can be "YES" or "NO". Default: "YES".

FIRST_COL

(read-only, non inheritable)

Returns the number of the first visible column.

FIRST_LINE

(read-only, non inheritable)

Returns the number of the first visible line.

FULL_VISIBLE

(write-only, non inheritable)

Tries to show completely a specific cell (considering any vertical or horizontal header or scrollbar position). This attribute is set by a formatted string "%d:%d" (C syntax), where each "%d" represent the line and column integer indexes respectively.

IMAGE_CANVAS

(read-only, non inheritable)

Returns the internal image CD canvas (reference to IUP::Canvas) ZZZ-test-this This attribute should be used only in specific cases and by experienced programmers.

LIMITS(L):(C)

(read-only, non inheritable)

Where (L) is the line number and (C) the column number - e.g. "LIMITS11:25". Returns the limits of a given cell. Output format is a string "xmin:xmax:ymin:ymax".

NON_SCROLLABLE_LINES

Determines the number of non-scrollable lines (vertical headers) that should always be visible despite the vertical scrollbar position. It can be any non-negative integer value. Default: "0"

NON_SCROLLABLE_COLS

Determines the number of non-scrollable columns (horizontal headers) that should always be visible despite the horizontal scrollbar position. It can be any non-negative integer value. Default: "0"

ORIGIN

Sets the first visible line and column positions. This attribute is set by a formatted string "%d:%d" (C syntax), where each "%d" represent the line and column integer indexes respectively.

REPAINT

(write-only, non inheritable)

When set with any value, provokes the control to be redrawn.

SIZE

(non inheritable)

There is no initial size. You must define SIZE or RASTERSIZE.

SCROLLBAR

(creation only)

Default: "YES".

The following common attributes are also accepted:

ACTIVE, BGCOLOR, FONT, X, Y, POSITION, MINSIZE, MAXSIZE, WID, TIP, SIZE, RASTERSIZE, ZORDER, VISIBLE

CALLBACKS

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

DRAW_CB

Called when a specific cell needs to be redrawn.

Callback handler prototype:

sub draw_cb_handler {
  my ($self, $line, $column, $xmin, $xmax, $ymin, $ymax, $canvas) = @_;
  #...
}

$self - reference to the element (IUP::Cells) that activated the event

$line, $column - the grid position inside the control that is being redrawn, in grid coordinates.

$xmin, $xmax, $ymin, $ymax - the raster bounding box of the redrawn cells, where the application can use CD functions to draw anything. If the attribute IUP_CLIPPED is set (the default), all CD graphical primitives is clipped to the bounding region.

$canvas - internal canvas CD used to draw the cells.

HEIGHT_CB

Called when the controls needs to know a (eventually new) line height.

Callback handler prototype:

sub height_cb_handler {
  my ($self, $line) = @_;
  #...
}

$self - reference to the element (IUP::Cells) that activated the event

$line - the line index

Returns - an integer that specifies the desired height (in pixels). Default is 30 pixels.

HSPAN_CB

Called when the control needs to know if a cell should be horizontally spanned.

Callback handler prototype:

sub hspan_cb_handler {
  my ($self, $line, $column) = @_;
  #...
}

$self - reference to the element (IUP::Cells) that activated the event

$line, $column - the line and column indexes (in grid coordinates)

Returns - an integer that specifies the desired span. Default is 1 (no span).

MOUSECLICK_CB

Called when a color is selected. The primary color is selected with the left mouse button, and if existent the secondary is selected with the right mouse button.

Callback handler prototype:

sub mouseclick_cb_handler {
  my ($self, $button, $pressed, $line, $column, $x, $y, $status) = @_;
  #...
}

$self - reference to the element (IUP::Cells) that activated the event

$button, $pressed, $x, $y, $status - same as the BUTTON_CB by IUP::Canvas.

$line, $column - the grid position in the control where the event has occurred, in grid coordinates.

MOUSEMOTION_CB

Called when the mouse moves over the control.

Callback handler prototype:

sub mousemotion_cb_handler {
  my ($self, $line, $column, $x, $y, $status) = @_;
  #...
}

$self - reference to the element (IUP::Cells) that activated the event

$x, $y, $status - same as the MOTION_CB by IUP::Canvas.

$line, $column - the grid position in the control where the event has occurred, in grid coordinates.

NCOLS_CB

Called when then controls needs to know its number of columns.

Callback handler prototype:

sub ncols_cb_handler {
  my $self = shift;
  #...
}

$self - reference to the element (IUP::Cells) that activated the event.

Returns - an integer that specifies the number of columns. Default is 10 columns.

NLINES_CB

Called when then controls needs to know its number of lines.

Callback handler prototype:

sub nlines_cb_handler {
  my $self = shift;
  #...
}

$self - reference to the element (IUP::Cells) that activated the event.

Returns - an integer that specifies the number of lines. Default is 10 lines.

SCROLLING_CB

Called when the scrollbars are activated.

Callback handler prototype:

sub scrolling_cb_handler {
  my ($self, $line, $column) = @_
  #...
}

$self - reference to the element (IUP::Cells) that activated the event.

$line, $column - the first visible line and column indexes (in grid coordinates).

Returns - if IUP_IGNORE the cell is not redrawn. By default the cell is always redrawn.

VSPAN_CB

Called when the control needs to know if a cell should be vertically spanned.

Callback handler prototype:

sub vspan_cb_handler {
  my ($self, $line, $column) = @_
  #...
}

$self - reference to the element (IUP::Cells) that activated the event.

$line, $column - the line and column indexes (in grid coordinates).

Returns - an integer that specifies the desired span. Default is 1 (no span).

WIDTH_CB

Called when the controls needs to know the column width.

Callback handler prototype:

sub width_cb_handler {
  my ($self, $column) = @_
  #...
}

$self - reference to the element (IUP::Cells) that activated the event.

$column - the column index.

Returns - an integer that specifies the desired width (in pixels). Default is 60 pixels.

The following common callbacks are also accepted:

MAP_CB, UNMAP_CB, GETFOCUS_CB, KILLFOCUS_CB, ENTERWINDOW_CB, LEAVEWINDOW_CB, K_ANY, HELP_CB

EXAMPLES

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

0-basic/cells_checkboard.pl - IUP::Cells example
0-basic/cells_degrade.pl - IUP::Cells example
0-basic/cells_numbering.pl - IUP::Cells example

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

DESCRIPTION

USAGE

CREATION - new() method

ATTRIBUTES

CALLBACKS

EXAMPLES

SEE ALSO

Module Install Instructions