NAME

Curses::UI::Grid - Create and manipulate data in grid model

CLASS HIERARCHY

Curses::UI::Widget
   |
   +----Curses::UI::Grid

SYNOPSIS

use Curses::UI;
my $cui = new Curses::UI;
my $win = $cui->add('window_id', 'Window');
my $grid =$win->add(
  'mygrid', 'Grid'
  -rows    => 3,
  -columns => 5,
);

# set header desc 
$grid->set_label("cell$_", "Head $_")
  for (1 .. 5);

# add some data
$grid->set_cell_value("row1", "cell$_", "value $_")
  for 1 .. 5;
my $val = $grid->get_value("row1", "cell2");

DESCRIPTION

 Curses::UI::Grid is a widget that can be used to
 browsing or manipulate data in grid model


See exampes/grid-demo.pl in the distribution for a short demo.

STANDARD OPTIONS

-parent, -x, -y, -width, -height, -pad, -padleft,
-padright, -padtop, -padbottom, -ipad, -ipadleft,
-ipadright, -ipadtop, -ipadbottom, -title,
-titlefull-width, -titlereverse, -onfocus, -onblur,
-fg,-bg,-bfg,-bbg

-basebindings < HASHREF >

Basebindings is assigned to bindings with editbindings if editable option is set.

Hash key is a keystroke and the value is a routines that will be bound. In the event key is empty, the corresponding routine will become the default routine for all not mapped keys.

process_bindings applies to unmatched keystrokes it receives.

By default, the following mappings are used for basebindings:
```
KEY                 ROUTINE
------------------  ----------
CUI_TAB             next_cell
KEY_ENTER()         next_cell
KEY_BTAB()          prev-cell
KEY_UP()            prev_row
KEY_DOWN()          next_row
KEY_RIGHT()         cursor_right
KEY_LEFT()          cursor_left
KEY_HOME()          cursor_home
KEY_END()           cursor_end
KEY_PPAGE()         grid_pageup
KEY_NPAGE()         grid_pagedown
```

-editindings < HASHREF >

By default, the following mappings are used for basebindings:

KEY                 ROUTINE
------------------  ----------
any                 add_string
KEY_DC()            delete_character
KEY_BACKSPACE()     backspace
KEY_IC()            insert_row
KEY_SDC()           delete_row

-routines < HASHREF >

ROUTINE          ACTION
----------       -------------------------
loose_focus      loose grid focus
first_row        make first row active
last_row         make last  row active
grid-pageup      trigger event -onnextpage
grid-pagedown    trigger event -onprevpage

next_row         make next row active
prev_row         make prev row active


next_cell        make next cell active
prev_cell        make prev cell active
first_cell       make first row active
last_cell        make last  row active

cursor_home      move cursor into home pos in focused cell
cursor_end       move cursor into end pos in focused cell
cursor_righ      move cursor right in focused cell
cursor_left      move cursor left in focused cell
add_string       add string to focused cell
delete_row       delete active row from grid, shift rows upstairs
insert_row       insert row in current position

delete_character delete_character from focused cell
backspace        delete_character from focused cell

-editable < BOOLEAN >

The grid widget will be created as a editable grid for the truth value, otherwise it will be in read only mode (data viewer) Default value is true.
-columns < COLUMNS >

This option control how many cell objects should be created for the grid widget. Default value is 0. If this value is set to non FALSE, construtor creates empty cells.
-rows < ROWS >

This option control how many row objects should be created for the grid widget. Default value is 0. If this value is set to non FALSE, construtor creates empty rows.
-count < COUNT >

This option store logical number of all rows. It can be used for calculating vertical scroll.
-page < NUMBER >

This option store logical number of current page. It can be used for calculating vertical scroll.

GRID EVENTS

-onnextpage < CODEREF >

This sets the onnextpage event handler for the widget. If the widget trigger event nextpage, the code in CODEREF will be executed.
-onprevpage < CODEREF >

This sets the onnextpage event handler for the widget. If the widget trigger event previouspage, the code in CODEREF will be executed.

GRID-ROW-SPECIFIC OPTIONS

-onrowdraw < CODEREF >

This sets the onrowdraw event handler for the widget. If the widget trigger event rowdraw, the code in CODEREF will be executed. This can be useful for dynamically setting colors appropriate to some conditions.

my $grid=$w->add('grid'
  'Grid',
  -rows      => 3,
  -columns   => 4,
  -onrowdraw => sub {
    my $row = shift;
    #check conditions and set color for row
    my $value = $row->get_value('cell0');
        # some stuff here
        #....
    if ( .... ) {
        $row->bg('black');
        $row->fg('yellow');
    } else { 
      # return back to origin color
      $row->bg(''); 
      $row->fg(''); 
    }
  },
);

-onrowfocus < CODEREF >

This sets the onrowfocus event handler for the widget. If the widget trigger event rowfocus, the code in CODEREF will be executed.
-onrowblur < CODEREF >

This sets the onrowblur event handler for the widget. If the widget trigger event rowblur, the code in CODEREF will be executed. The CODEREF can return FALSE to cancel rowblur action and current row will not lose the focus.
-onrowchange < CODEREF >

This sets the onrowchange event handler for the widget. If the widget trigger event rowchange, the code in CODEREF will be executed. The CODEREF can return FALSE to cancel onrowblur action and current row will not lose the focus.
-onbeforerowinsert < CODEREF >

This sets the onbeforerowinsert event handler for the widget. If the widget trigger event onbeforerowinsert, the code in CODEREF will be executed. The CODEREF can return FALSE to cancel insert_row action See more about insert_row method.
-onrowinsert < CODEREF >

This sets the oninsert event handler for the widget. If the row widget trigger event onrowinsert, the code in CODEREF will be executed. See more about insert_row method.
-onrowdelete < CODEREF >

This sets the onrowdelete event handler for the widget. If the widget trigger event onrowdelete, the code in CODEREF will be executed. The CODEREF can return FALSE to cancel delete_row action See more about delete_row method.
-onfterrowdelete < CODEREF > This sets the onrowdelete event handler for the widget. If the widget trigger event onrowdelete, the code in CODEREF will be executed. See more about delete_row method

GRID-CELL-SPECIFIC OPTIONS

-oncelldraw < CODEREF >

This sets the oncelldraw event handler for the widget. If the widget trigger event celldraw, the code in CODEREF will be executed. Gets the cell widget reference as its argument.
-oncellfocus < CODEREF >

This sets the oncellfocus event handler for the widget. If the widget trigger event cellfocus, the code in CODEREF will be executed. Gets the cell widget reference as its argument.
-oncellblur < CODEREF >

This sets the oncellblur event handler for the widget. If the widget trigger event cellblur, the code in CODEREF will be executed. Gets the cell widget reference as its argument. The CODEREF can return FALSE to cancel oncellblur action and current cell will not lose the focus.
```
my $grid = $w->add('grid'
    'Grid'
    -rows     => 3,
    -columns  => 4,
    -oncellblur => sub {
        my $cell=shift;
        # some validation 
        if(... ) {
              return 0; # cancel oncellblur event
        }
        $cell;
    },
);
```

-oncellchange < CODEREF >

This sets the oncellchange event handler for the widget. If the widget trigger event cellchange, the code in CODEREF will be executed. Gets the cell widget reference as its argument. The CODEREF can return FALSE to cancel oncellblur action and current cell will not lose the focus.

my $grid=$w->add('grid'
  'Grid',
  -rows       => 3,
  -columns    => 4,
  -oncellblur => sub {
      my $cell=shift;
      my $old_value=$cell->text_undo;
      my $value=$cell->text;
      # some validation 
      if(... ) {
          return 0; # cancell oncellchange and oncellblur event 
      }
      return $cell;
      }
);

-oncellkeypress < CODEREF >

This sets the oncellkeypress event handler for the widget. If the widget trigger event cellkeypress, the code in CODEREF will be executed. Gets the cell widget reference and added string as its argument. The cellkeypress event is called by method add_string in cell obejct. The CODEREF can return FALSE to cancel add_string action.
-oncelllayout < CODEREF >

This sets the oncelllayout event handler for the widget. If the widget trigger event cellkeypress, the code in CODEREF will be executed. Gets the cell widget reference and value as its argument. The CODEREF can return any text which will be proceeded insted of the orgin value.
```
my $grid = $w->add('grid'
  'Grid',
  -rows         => 3,
  -columns      => 4,
  -oncelllayout => sub {
      my $cell = shift;
      my $value = $cell->text;
      # mask your value
      ....
      return $value;
  }
);
```

METHODS

debug_msg

Debugs messages.

new( OPTIONS )

Constructs a new grid object. Takes list of options as parameters.

initialise( OPTIONS )

Initialises Grid object

id2cell

Return cell object, taks cell id.

editable( BOOLEAN )

Sets bindings model for editable gird if passed in varaible is true, otherwise read-only model will be set.

bindings

Sets/gets binigs for Grid.

create_default_rows( OPTIONS )

Creates defaults rows for grid. Takes grid options as parameters. Number of rows to be created is taken from -rows options passed in or from -rows grid's attribute

create_default_cells( OPTIONS )

Creates defaults cells for grid. Takes grid options as parameters. Number of rows to be created is taken from -cells options passed in or from -cells grid's attribute

current_cell_index

Sets/gets current cell index.

current_cell_id( INDEX )

Returns current cell id. Takes cell position index.

cell_index_for_id

cell( ID, cell )

Sets/gets cell for passed in id.

_cells

Returns id cells list.

cells_count

Returns number of defined cells - 1;

cell_for_x_position

Return cell for passed in x position.

current_row_index

Sets/gets current row index.

current_row_id( INDEX )

Returns current row id. Takes row position index.

row_index_for_id

row( ID, ROW )

Sets/gets row for passed in id.

row_for_index

Returns row for passed in y position

_rows

Returns is rows list.

rows_count

Returns number of defined rows -1;

add_row( ID, OPTIONS )

Adds a row to grid. Takes the row id and row options. For available options see Curses::UI::Grid::Row. Returns the row object or undef on failure.

delete_row( POSITION )

This routine will delete row data from passed in possition - default current position. The function calls event onrowdelete, shifts others row up and runs event onafterrowdelete and remove last row if onafterrowdelete CODEREF doesn't return FALSE.

Note. If onrowdelete CODEREF returns FALSE then the delete_row routine will be cancelled. Returns TRUE or FALSE on failure.

insert_row( POSITION )

This routine will add empty row data to grid at cureent position. All row data below curent row will be shifted down. Add_row method will be called if rows number is less than page size. Then onrowinsert event is called with row object as parameter. Returns the row object or undef on failure.

reorganize_rows( POSITION, DIRECTION )

Rewrites rows properties from grid, starts from passed in position, direction tells if shifts or pops other rows up or down

_delete_row( BOOLEAN )

This routine will delete last row object from grid. Redraws immediate grid if passed in value is TRUE. Returns TRUE or FALSE on failure.

add_cell( ID, OPTIONS )

This routine will add cell to grid using options in the HASH options. For available options see Curses::UI::Grid::Cell. Returns the cell object or undef on failure.

_delete_cell( ID )

This routine will delete given cell. Returns TRUE or FALSE on failure.

add( ID, CLASS, OPTIONS )

Adds cell or row object to grid.

get_cell( ID | CELL )

Returns cell, takes cell's id or cell.

get_row( ID | ROW )

Returns row, takes row's id or row object.

set_label( CELL_ID, LABEL )

Sets lable for passed in cell object.

set_cell_width( CELL_ID, WIDTH )

Sets width for passed in cell object.

get_foused_row

Return focused row if rows defined.

getfocusrow

See get_foused_row.

get_foused_cell

Return focused cell if cells defined.

getfocuscell

See get_foused_cell.

get_last_row

Returns last row.

get_first_row

Returns first row.

page

Sets/gets page number.

page_size

Sets/gets page size.

Layout methods

layout: Lays out the grid object with rows and cells, makes sure it fits on the available screen.
layout_content
layout_cells: Horizontal cells layout of the screen.
layout_horizontal_scrollbar.: Layouts horizontal scrollbar, takes total cells width
layout_vertical_scrollbar.: Layouts vertical scrollbar, takes total cells width
get_x_offset_to_obj: Returns position to the x_offset for a new focued cell, takes a cell object as parameter.
vertical_lines: Gets/sets vertical lines.
add_vline: Adds vline that will be drawn.
clear_vline: Clears vertcal lines position.
focus_row( ROW, FORCE, DIRECTION ): Moves focus to passed in row.
focus_cell( ROW, FORCE, DIRECTION ): Moves focus to passed in cell.
focus_obj( TYPE, OBJECT, FORCE, DIRECTION ): Moves focus to passed in object. Takes TYPE that can be row or cell. Force parameter is boolean and force changing focus in case focus events fails.
event_onfocus: Calls supercall events onfocus

Draw methods

draw( BOOLEAN )

Draws the grid object along with the rows and cells. If BOOLEAN is true, the screen is not updated after drawing.

By default, BOOLEAN is true so the screen is updated.

draw_grid

Draws grid.

draw_header_vline

Draws header lines.

x_offset

Sets/gets x offset for grid.

Colors methods

set_color( BG_COLOR, FG_COLOR, CANVAS ): Sets color for passed in canvaed object. Returns color pair.
color_off( COLOR_PAIR, CANVAS ): Sets color for passed in canvaed object

Event functions

run_event( EVENT, OBJECT): Runs passed event, takes event name as first parameter and row or cell or grid object as caller.
is_event_defined( EVENT ): Returns true if passed in event is defined.

Data maipulation methods

set_value( ROW , CELL , VALUE )

This routine will set value for given row and cell. CELL can by either cell object or id cell. ROW can by either row object or id row.

set_values( ROW , HASH )

This routine will set values for given row. HASH should contain cells id as keys and coredpondend values. ROW can by either row object or id row.

$grid->set_values('row1',cell1=>'cell 1',cell4=>'cell 4');

$grid->set_values('row1',cell2=>'cell 2',cell3=>'cell 3');

This method will not affect cells which are not given in HASH.

get_value( ROW, CELL )

This routine will return value for given row and cell. CELL can by either cell object or id cell. ROW can by either row object or id row.

get_values ( ROW )

This routine will return HASH values for given row. HASH will be contain cell id as key. ROW can by either row object or id row.

get_values_ref ( ROW )

This routine will return HASH reference for given row values. ROW can by either row object or id row.

my $ref=$grid->get_values_ref('row1');
  $$ref{cell1} = 'cell 1 ';
  $$ref{cell2} = 'cell 2 ';
  $$ref{cell3} = 'cell 3 ';
  $grid->draw();

Note. After seting values by reference you should call draw method.

next_row: Return next row object.
prev_row: Return previous row object.
first_row: Return first row object.
last_row: Return last row object.
grid_pageup( BOOLEAN ): Calls grid onprevpage event. Redraws immediate grid if passed in value is TRUE.
grid_pagedown( BOOLEAN ): Calls grid onnextpage event. Redraws immediate grid if passed in value is TRUE.
first_cell: Returns first cell object.
last_cell: Returns last cell object.
prev_cell: Returns previous cell object.
next_cell: Returns next cell object.

Cells methods.

cursor_left: Calls cursor left on focsed cell. Return focued cells.
cursor_right: Calls cursor right on focsed cell. Return focued cells.
cursor_to_home: Calls cursor home on focsed cell. Return focued cells.
cursor_to_end: Calls cursor end on focsed cell. Return focued cells.
delete_character: Calls delete character on focsed cell. Return focued cells.
backspace: Calls backspace on focsed cell. Return focued cells.
add_string: Calls add_string on focsed cell. Return focued cells.

Mouse event method.

mouse_button1

AUTHOR

COPYRIGHT AND LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itthis.

To install Curses::UI::Grid, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Curses::UI::Grid

CPAN shell

perl -MCPAN -e shell
install Curses::UI::Grid

For more information on module installation, please visit the detailed CPAN module installation guide.

	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

CLASS HIERARCHY

SYNOPSIS

DESCRIPTION

STANDARD OPTIONS

WIDGET-SPECIFIC OPTIONS

GRID EVENTS

GRID-ROW-SPECIFIC OPTIONS

GRID-CELL-SPECIFIC OPTIONS

METHODS

Layout methods

Draw methods

Colors methods

Event functions

Data maipulation methods

Navigation methods.

Cells methods.

Mouse event method.

SEE ALSO

AUTHOR

COPYRIGHT AND LICENSE

NAME

CLASS HIERARCHY

SYNOPSIS

DESCRIPTION

STANDARD OPTIONS

WIDGET-SPECIFIC OPTIONS

GRID EVENTS

GRID-ROW-SPECIFIC OPTIONS

GRID-CELL-SPECIFIC OPTIONS

METHODS

Layout methods

Draw methods

Colors methods

Event functions

Data maipulation methods

Navigation methods.

Cells methods.

Mouse event method.

SEE ALSO

AUTHOR

COPYRIGHT AND LICENSE

Module Install Instructions