NAME

SharkAPI::Grid.pm - SharkAPI Grid Module

DESCRIPTION

This module contains some helper functions that simplify the display of data from a DBI datasource in a GTK+ CList. The sql statement passed to the execute command controls the column names and key values stored for each row. An existing GtkScrolledWindow object and a SharkAPI::DB object is passed to link with the datasource.

Setup Example:

  # setup grid object and link select row handler
  $Grid_Sample::grid = SharkAPI::Grid->new(
      $Grid_Sample::app, 'result_window', $Grid_Sample::db);
  $Grid_Sample::grid->grid_handler('select_row',
       \&Grid_Sample::select);

Execute Example:

  # grid sql
  $gsql = q{select custnum  as "key1",
                   custnum  as "Cust Num",
                   custname as "Name",
                   address  as "Address",
                   phone    as "Phone"
              from customers
             order by custnum};

  # execute and display results
  $Grid_Sample::grid->grid_execute_sql($gsql, 1);

Any text within the tags <PERL></PERL> will be executed and the results placed into the sql statement. This can be used to allow dynamic values to be entered into the sql statement.

Example:

  $gsql = q{select custnum  as "key1",
                   custname as "key2",
                   custnum  as "Cust Num",
                   custname as "Name",
                   address  as "Address",
                   phone    as "Phone"
              from customers
             order by <PERL>print 'custname';</PERL>};

When the SharkAPI::Grid object is executed the statement will look as follows:

  select custnum  as "key1",
         custname as "key2",
         custnum  as "Cust Num",
         custname as "Name",
         address  as "Address",
         phone    as "Phone"
    from customers
   order by custname

Row Keys:

Any column name that begins with key and is followed by a number will be assigned to the row as row data array. Here is an example of a select handler that was assigned above.

sub Grid_Sample::select { my ($widget, $row, $column) = @_;

  my $data = $Grid_Sample::grid->grid_data($row);

  print "key values:" . join(',', @$data) . "\n";
}
 
=head1 OBJECT INTERFACE

new ( $app_obj, $parent_widget_name, $db )

New creates the Grid object. It either returns the object on successful creation or undef upon failure. $! is the error code if any. The GtkClist object is added to the parent widget with gtk_add_with_viewport. The SharkAPI::DB object is used to link with the datasource and the SharkAPI::App object is used for application context. The object contains the following hash members:

db SharkAPI::DB object

swin the parent widget object (should be ScrolledWindow)

list the GtkClist object

app_obj the SharkAPI::App object

name the name of the parent widget

HANDLERS a hash of handler functions

grid_handler ( $handler, $func )

This function assigns the $func function reference to the specified handler. The following handers exsit, ``select_row'' and ``double_click''.

Example:

  $Grid_Sample::grid->grid_handler('select_row',
       \&Grid_Sample::select);

grid_data ( $row )

Returns the row data associated with the specified row.

grid_execute_sql ( $sql, $autosize )

This functions executes the specified sql statement against the SharkAPI::DB object setup at object creation and displays the results in a newly created GtkClist. The old or existing GtkClist is destroyed and a new object created. If the autosize parameter is ``true'' then the autosize function is called on the resulting GtkClist. See above for examples of sql statements.

set_handlers ( )

This function ``re-applies'' the handlers that were set with the SharkAPI::Grid::grid_handler function. This is used to put the handlers back on the newly created GtkClist object.

AUTHOR

Bill Walz, bill@landsharklinux.com