Glade::PerlRun 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::PerlRun and quotes Glade::PerlRun
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::PerlRun object
e.g. my $Object = Glade::PerlRun->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()
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');
2) OPTIONS HANDLING METHODS
These methods will load, merge, reduce and save a hierarchical options
structure that is stored in one or more XML files and accessed with
AUTOLOAD methods.
options(%params)
Loads and merges all app options.
e.g. Glade::PerlRun->options(%params);
my options = $Object->options(%params);
normalise($value)
Return a normalised value ie. convert 'True'|'Yes'|'y'|'On' to 1
and 'False'|'No'|'n'|'Off' to 0.
The comparisons are case-insensitive.
e.g. my $normalised_value = Glade::PerlRun->normalise('True');
Recursively merge a hash into an existing one - overwriting any keys with
a defined value. It will also optionally set accessors for the keys to be
used via AUTOLOAD().
e.g. $new_hash_ref = Glade::PerlRun->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.
save_app_options($mru, %defaults)
Updates mru and saves all app/user options. This will save the mru file
in the user options file (if one is named in
$class->{$class->type}->xml->user).
e.g. Glade::PerlRun->save_app_options($mru_filename);
save_options($filename, %app_defaults)
Reduce and save the supplied options to the file specified.
e.g. $Object->save_options;
write_options($options, $filename)
Write an options hash to XML file.
e.g. my options = $Object->write_options($hash_ref, '/path/to/file');
Removes any options that are equivalent to site/user/project options
or that are specified to be pruned. We will descend into any hash types
specified.
e.g. my options = $Object->reduce_hash(
$options_to_reduce,
$user_options,
$site_options,
$app_defaults,
$base_defaults '*work*proto*',
'*My::Class*');
save_file_from_string($filename, $string)
Write a string to a file.
e.g. Glade::PerlRun->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 '__S' or '__D')
e.g. "sprintf(gettext('__S', "A message '%s'"), $value);"
start_checking_gettext_strings()
Start checking and storing missing translations in language type
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::PerlRun->show_skeleton_message(
$me, \@_, __PACKAGE__, ``$Glade::PerlRun::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::PerlRun::data.
e.g. Glade::PerlRun->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
# widget for user data
6) GENERAL METHODS
These are some general purpose methods that are useful to Glade::PerlGenerate
and generated apps.
full_Path()
Turn a relative path name into an absolute path
e.g. my $path = Glade::PerlRun->full_Path($relative_path, $directory);
relative_Path($basepath, $path, $root)
Turn an absolute path name into a relative path
e.g. my $path = Glade::PerlRun->relative_Path($relative_path, $directory);
string_from_File()
Reads (slurps) a file into a string
e.g. my $string = Glade::PerlRun->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.