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 
    for my $i(1 .. 5) {$g->set_label("cell$i","Head ".$i);}
    # add some data
    for my $i(1 .. 5) {$g->set_cell_value("row1","cell".$i,"value $i");}
    my $val=$g->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.

  The keys in bindings hash reference are keystrokes and the values are routines to which they should be bound. In the event a key is empty, the corresponding routine will become the default routine that

  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. Otherwise it will be able only view data (data viewer) if BOOLEAN is false. By default BOOLEAN is true.

• -columns < COLUMNS >

  This option control how many cell objects should be kept in memory for the grid widget. By default 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 kept in memory for the grid widget. By default 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 could be used for calculating vertical scroll.

• -page < NUMBER >

  This option store logical number of current page. It could 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. It will get the widget reference as its argument.

• -onprevpage < CODEREF >

  This sets the onnextpage event handler for the widget. If the widget trigger event previouspage, the code in CODEREF will be executed. It will get the widget reference as its argument.

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. It will get the widget reference as its argument. This could 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 $v=$row->get_value('cell0');
  		....
  		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. It will get the row widget reference as its argument.

• -onrowblur < CODEREF >

  This sets the onrowblur event handler for the widget. If the widget trigger event rowblur, the code in CODEREF will be executed. It will get the row widget reference as its argument. The CODEREF could 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. It will get the row widget reference as its argument. The CODEREF could return FALSE to cancel onrowblur 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. It will get the row widget reference as its argument. The CODEREF could 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. It will get the grid widget reference as its argument. The CODEREF could 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. It will get the row widget reference as its argument. 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. It will get the row widget reference as its argument. The CODEREF could 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. It will get the row widget reference as its argument. See more about delete_row method

  back

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. It will get 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. It will get 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. It will get the cell widget reference as its argument. The CODEREF could 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
              }
              return $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. It will get the cell widget reference as its argument. The CODEREF could 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. It will get the cell widget reference and added string as its argument. Actually the cellkeypress event is called by method add_string in cell obejct. The CODEREF could 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. It will get the cell widget reference and value as its argument. The CODEREF could 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

• new ( OPTIONS ) Constructs a new grid object using options in the hash OPTIONS.

• layout ( )

  Lays out the grid object with rows and cells, makes sure it fits on the available screen.

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

• focus ( )

• onFocus ( CODEREF )

• onBlur ( CODEREF )

  See Curses::UI::Widget for explanations of these methods.

GRID-MODEL FUNCTIONS

• insert_row

  This routine will add empty row data to grid at cureent position. All row data below curent row will be shifted down. Then function will call event onbeforerowinsert with grid obj as parameter. Otherwise 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.

• delelete_row ( )

  This routine will delete row data from 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.

• add_row ( OPTIONS )

  This routine will add row to grid using options in the hash OPTIONS. For available options see Curses::UI::Grid::Row. Returns the row object or undef on failure.

• del_row ( )

  This routine will delete last row. Returns TRUE or FALSE on failure.

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

• del_cell ( ID )

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

• get_cell ( ID )

  This routine will return given cell object.

• get_row ( ID )

  This routine will return given row object.

• set_label ( ID , VALUE )

  This routine will set header title for cell object

• getfocusrow

  This routine will return focused row object.

• getfocuscell

  This routine will return focused cell object.

• page_size

  This routine will return page_size attribute (canvasheight - 2).

• page

  This routine will return page attribute.

DATA-MANIPULATION FUNCTIONS

• set_value ( ROW , CELL , VALUE )

  This routine will set value for given row and cell. CELL could by either cell object or id cell. ROW could 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. ROW could 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 could by either cell object or id cell. ROW could 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 could by either row object or id row.

• get_values_ref ( ROW )

  This routine will return HASH reference for given row values. ROW could 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.

GRID-NAWIGATION FUNCTIONS

• grid_pageup

• grid_pagedown

• focus_row

• first_row

• last_row

• next_row

• prev_row

• focus_cell

• next_cell

• prev_cell

• first_cell

• last_cell

• get_first_row

• get_last_row

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

User Interfaces

cpanm Curses::UI::Grid

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