NAME

SharkAPI::Console.pm -- Console/Logging Module

DESCRIPTION

The console package provides a simple console log and logging functions. Perl code can also be loaded from the console. This feature allows code to be modified and read without restarting an application.

SYNOPSIS

The console module can be used as follows, the $app_obj should be a valid SharkAPI::app object with an established application object:

  # construct new console object
  my $console = SharkAPI::Console->new($app_obj);
  # setup logging flags
  $console->console_logging('SQL',1,1);
  $console->console_logging('MSG',1,1);
  $console->console_pump(0); # don't run events yet since we
                                      # are not in GtkMain yet.
  # display the console log
  $console->console_show();
  # set the pump flag, #### don't log anything until after gtk Main.
  $console->console_pump(1)

  # Log Function
  sub mylog {
    my ($type, $data, $prefix, $level) = @_;

    $console->console_print($type, $data, $prefix, $level)
      if defined $console;
  }

For an example see the console sample in the ``sample'' directory.

OBJECT INTERFACE

new ( $app_obj )

New creates the Console object. It should be passed a SharkAPI::App object. It either returns the object on successful creation or undef upon failure. $! is set the the error code if any.

console_show ()

console_show will display the console window.

console_hide ()

console_hide will hide the console window.

console_clear ()

console_clear will clear the console window.

console_print ( $type, $data, $prefix, $level )

console_print will write $data to the log window. The %logging hash is checked to see if the data should be written. Also the $data is prefixed with the prefix value in the hash along with the prefix passed to console_print function.

console_xml ()

console_xml will return the Snapper application xml that defines the console window.

console_logging ( $type, $level, $do, $prefix, $extra )

console_logging controls values defined in the logging hash. The logging hash controls when and what is logged when the console_print function is called. The values passed are applied to the hash. Please note that a numeric value should be passed for $level, the string 'level' will be prefixed to the value.

The logging hash is initialized as follows:

  %SharkAPI::Console::logging =
    (
     'level1' => {                # logging level
         'SQL' => {               # logging type
             'do'     => '0',     # log data if non-zero
             'prefix' => 'sql',   # prefix data with this value
             'extra'  => '',      # append this value after prefix
         },
         'PERL' => {
             'do'     => '0',
             'prefix' => 'perl',
             'extra'  => '',
         },
         'MSG' => {
             'do'     => '0',
             'prefix' => 'msg',
             'extra'  => '',
         }
     }
     );

SharkAPI::Console::logging is exported and can be modified to control the behavior of the logging functions.

console_pump ( $flag )

Toggle the pump flag. If this flag is non-zero then Gtk->main_iteration_do is called until all events are processed. This is needed to control the log before the calling application drops into Gtk Main.

If Gtk->main_iteration_do is called before Gtk Main then the program will hang.

AUTHOR

Bill Walz, bill@landsharklinux.com