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

WIDGET-SPECIFIC OPTIONS

• -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.

id

readonly

canvasscr

Returns canva ref.

test_more

Returns flag if uses test mode.

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.

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.

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.

Navigation methods.

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

SEE ALSO

Curses::UI::Grid::Row Curses::UI::Grid::Cell

AUTHOR

Copyright (c) 2004 by Adrian Witas. All rights reserved.

COPYRIGHT AND LICENSE

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

cpanm Curses::UI::Grid

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