Dermot Musgrove > Glade-Perl-Two-0.01 > Glade::Two::Run

Download:
Glade-Perl-Two-0.01.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.01   Source  

NAME ^

Glade::Two::Run - Utility methods for Glade-Perl (and generated applications).

SYNOPSIS ^

 use vars qw(@ISA);
 use Glade::Two::Run qw(:METHODS :VARS);
 @ISA = qw( Glade::Two::Run );

 # 1) CLASS methods
 my $Object = Glade::Two::Run->new(%params);
 $Object->glade->file($supplied_path);
 $widget = $window->lookup_widget('clist1');

 # 2) OPTIONS handling
 $options = Glade::Two::Run->options(%params);
 $normalised_value = Glade::Two::Run->normalise('True');
 $new_hash_ref = Glade::Two::Run->merge_into_hash_from(
      $to_hash_ref,      # Hash to be updated
      $from_hash_ref,    # Input data to be merged
      'set accessors');  # Any value will add AUTOLOAD() accessors
                         # for these keys.
 $Object->save_app_options($mru_filename);
 $Object->save_options;

 my $string = Glade::Two::Run->string_from_file('/path/to/file');
 Glade::Two::Run->save_file_from_string('/path/to/file', $string);

 # 3) Diagnostic message printing
 $Object->start_log('log_filename');
 $Object->diag_print(2, "This is a diagnostics message");
 $Object->diag_print(2, $hashref, "Prefix to message");
 $Object->stop_log;

 # 4) I18N
 Glade::Two::Run->load_translations('MyApp', 'fr', '/usr/local/share/locale/',
     undef, $SOURCE_LANG, 'Merge with already loaded translations');
 sprintf(_("A message '%s'"), $value);
 sprintf(gettext($SOURCE_LANG, "A message '%s'"), $value);
 Glade::Two::Run->start_checking_gettext_strings($SOURCE_LANG);
 Glade::Two::Run->stop_checking_gettext_strings($SOURCE_LANG);
 Glade::Two::Run->write_missing_gettext_strings($SOURCE_LANG);

 # 5) UI methods
 my $image = Glade::Two::Run->create_image('new.xpm', ['dir1', 'dir2']);
 my $pixmap = Glade::Two::Run->create_pixmap($form, 'new.xpm', ['dir1', 'dir2']);

 Glade::Two::Run->show_skeleton_message(
    $me, \@_, __PACKAGE__, "$Glade::Two::Run::pixmaps_directory/Logo.xpm");
 Glade::Two::Run->message_box(
    $message,                               # Message to display
    $title,                                 # Dialog title string
    [_('Dismiss'), _("Quit")." Program"],   # Buttons to show
    1,                                      # Default button is 1st
    $pixmap,                                # pixmap filename
    [&dismiss, &quit],                      # Button click handlers
    $entry_needed);                         # Whether to show an entry
                                            # widget for user data

 # 6) General methods
 $path = $Object->full_Path($Object->glade->file, $dir);
 $path = Glade::Two::Run->relative_Path($relative_path, $directory);

 $Object->reload_any_altered_modules;

DESCRIPTION ^

Glade::Two::Run provides some utility methods that Glade-Perl modules and also the generated classes need to run. These methods can be inherited and called in any app that use()s Glade::Two::Run and quotes Glade::Two::Run in its @ISA array.

Broadly, the utilities are of seven types.

 1) Class methods
 2) Options handling
 3) Diagnostic message printing
 4) I18N
 5) UI methods
 6) General methods

1) CLASS METHODS ^

The class methods provide an object constructor and data accessors.

new(%params)

Construct a Glade::Two::Run object

e.g. my $Object = Glade::Two::Run->new(%params);

AUTOLOAD()

Accesses all class data

e.g. my $glade_filename = $Object->glade->file; or $Object->glade->file('path/to/glade/file');

lookup_widget($widgetname)

Accesses a window or a form's widget by name

e.g. my $widget = $window->lookup_widget('clist1');

  OR my $form = $window->FORM; # or use $form in signal handlers
     my $widget = $form->lookup_widget('clist1');
fix_name($name)

Substitutes illegal characters in a perl name and returns it

e.g. my $name = Glade::Two::Run->fix_name($name); OR my $name = Glade::Two::Run->fix_name($name, 'TRANSLATE');

save_file_from_string($filename, $string)

Write a string to a file.

e.g. Glade::Two::Run->save_file_from_string('/path/to/file', $string);

3) DIAGNOSTIC MESSAGE METHODS ^

These methods will start logging diagnostic messages, produce standardised I18N messages and then stop logging and close any open files.

diag_print()

Prints diagnostics message (I18N translated) if verbosity is >= level specified

e.g. $Object->diag_print(2, "This is a diagnostics message"); $Object->diag_print(2, $hashref, "Prefix to message");

start_log()

Opens the log files and starts writing diagnostics

e.g. $Object->start_log('log_filename');

stop_log()

Loads site/user/project/params options

e.g. $Object->stop_log;

4) INTERNATIONALISATION (I18N) METHODS ^

These methods will load translations, translate messages, check for any missing translations and write a .pot file containing these missing messages.

_()

Translate a string into our current language

e.g. sprintf(_("A message '%s'"), $value);

gettext()

Translate into a preloaded language (eg $SOURCE_LANG or $DIAG_LANG)

e.g. sprintf(gettext($SOURCE_LANG, "A message '%s'"), $value);

start_checking_gettext_strings()

Start checking and storing missing translations in language type

  eg. $class->start_checking_gettext_strings($SOURCE_LANG);
stop_checking_gettext_strings()

Stop checking for missing translations in language type

  eg. $class->stop_checking_gettext_strings($SOURCE_LANG);
write_missing_gettext_strings()

Write a .pot file containing any untranslated strings in language type

  eg. $object->write_missing_gettext_strings($SOURCE_LANG);
load_translations()

Load a translation file (.mo) for later use as language type

  e.g. To load translations in current LANG from default locations
        $class->load_translations('MyApp');
  
  OR    $class->load_translations('MyApp', 'test', undef, 
            '/home/dermot/Devel/Glade-Perl/ppo/en.mo');

  OR    $class->load_translations('MyApp', 'fr', '/usr/local/share/locale/',
           undef, $DIAG_LANG, 'Merge with already loaded translations');

5) UI METHODS ^

These methods will provide some useful UI methods to load pixmaps and images and show message boxes of various types.

create_pixmap()

Create a gdk_pixmap and return it

e.g. my $pixmap = Glade::Two::Run->create_pixmap( $form, 'new.xpm', ['dir1', 'dir2']);

create_image()

Create and load a gdk_imlibimage and return it

e.g. my $image = Glade::Two::Run->create_image( 'new.xpm', ['dir1', 'dir2']);

create_image()

Create and load a gdk_pixbuf and return it

e.g. my $image = Glade::Two::Run->create_pixbuf( 'new.xpm', ['dir1', 'dir2']);

show_skeleton_message($class, $caller, $data, $package, $pixmap)

This method pops up a message_box to prove that a stub has been called. It shows a pixmap (logo) and buttons to dismiss the box or quit the app

 $caller    where we were called
 $data      the args that were supplied to the caller
 $package
 $pixmap    pixmap to show

e.g. Glade::Two::Run->show_skeleton_message( $me, \@_, __PACKAGE__, "$Glade::Two::Run::pixmaps_directory/Logo.xpm");

message_box()

Show a message box with optional pixmap and entry widget. After the dialog is closed, the data entered will be in global $Glade::Two::Run::data.

e.g. Glade::Two::Run->message_box( $message, # Message to display $title, # Dialog title string [_('Dismiss'), _("Quit")." Program"], # Buttons to show 1, # Default button is 1st $pixmap, # pixmap filename [&dismiss, &quit], # Button click handlers $entry_needed); # Whether to show an entry # widget for user data

6) GENERAL METHODS ^

These are some general purpose methods that are useful to Glade::Two::Generate and generated apps.

full_Path()

Turn a relative path name into an absolute path

e.g. my $path = Glade::Two::Run->full_Path($relative_path, $directory);

relative_Path($basepath, $path, $root)

Turn an absolute path name into a relative path

e.g. my $path = Glade::Two::Run->relative_Path($relative_path, $directory);

string_from_File()

Reads (slurps) a file into a string

e.g. my $string = Glade::Two::Run->string_from_file('/path/to/file');

reload_any_altered_modules()

Check all loaded modules and reload any that have been altered since the app started. This saves restarting the app for every change to the signal handlers or support modules.

It is impossible to reload the UI module (called something like ProjectUI.pm) while the app is running without crashing it so don't run glade2perl and then call this method. Similarly, any modules that construct objects in their own namespace will cause unpredictable failures.

I usually call this in a button's signal handler so that I can edit the modules and easily reload the edited versions of modules.

e.g. Glade::Two::Run->reload_any_altered_modules;

SEE ALSO ^

Glade::Two::Generate(3) glade2perl-2(1)

AUTHOR ^

Dermot Musgrove <dermot.musgrove@virgin.net>

syntax highlighting: