Padre::Wx::Role::Config

Padre::Wx::Role::ConfiUsermContributed Perl DocumePadre::Wx::Role::Config(3pm)



NAME
       Padre::Wx::Role::Config - Role for Wx forms that control preference
       data

DESCRIPTION
       Padre::Wx::Role::Config is a role for dialogs and form panels that
       enables the load and saving of configuration data in a standard manner.

       It was originally created to power the main Preferences dialog, but can
       be reused by any dialog of panel that wants to load preference entries
       and allow them to be changed.

       To use this role, create a dialog or panel which has public getter
       methods for the preference form elements. The public getter method must
       exactly match the name of the preference method you wish to load.

       For example, the following demonstrates a text box that can load and
       save the identify of the Padre user.

           # In your constructor, create the text control
           $self->{identity_name} = Wx::TextCtrl->new(
               $self,
               -1,
               "",
               Wx::DefaultPosition,
               Wx::DefaultSize,
           );

           # Later in the module, create a public getter for the control
           sub identity_name {
               $_[0]->{identity_name};
           }

       Once your public form controls have been set up, the preference
       information is loaded from configuration by the "config_load" method
       and then the "config_save" method is used to apply the changes to the
       active Padre instance and save the changes to configuration.

METHODS
   config_load
           $dialog->config_load(
               Padre::Current->config,
               qw{
                   identity_name
                   identity_nick
                   identity_email
               }
           );

       The "config_load" method loads preference information from
       configuration into the public form controls for the current object.

       The first parameter to "config_load" should be a valid Padre::Config
       object to load from (usually the main or current configuration object).

       After the configuration object you should provide a list of preferences
       names that should be loaded.

       Returns the number of configuration form controls that were
       successfully loaded, which should match the number of names you passed
       in.

   config_save
           $dialog->config_save(
               Padre::Current->config,
               qw{
                   identity_name
                   identity_nick
                   identity_email
               }
           );

       The "config_save" method saves preference information from public form
       controls into configuration, applying the changes to the current Padre
       instance as it does so.

       The first parameter to "config_load" should be a valid Padre::Config
       object to load from (usually the main or current configuration object).

       After the configuration object you should provide a list of preferences
       names that should be loaded.

       The changes are applied inside of a complete Padre::Lock of all
       possible subsystems and GUI lock modes to ensure that changes apply as
       a single fast visual change, and will not cause weird flickering of the
       user interface.

       Returns the number of changes that were made to configuration, which
       may be zero if all config fields match the current values. No lock will
       be taken in the case where the number of config changes to make is
       zero.

   config_diff
           $dialog->config_diff(
               Padre::Current->config,
               qw{
                   identity_name
                   identity_nick
                   identity_email
               }
           );

       The "config_diff" method calculates changes to preference information
       from the public form controls, but does not save or apply them.

       The first parameter to "config_load" should be a valid Padre::Config
       object to load from (usually the main or current configuration object).

       After the configuration object you should provide a list of preferences
       names that should be loaded.

       Since the "config_diff" method is used by "config_save" to find the
       list of changes to make, overloading "config_diff" with custom
       functionality will also result in this custom behaviour being used when
       saving the changes for real.

       Returns a reference to a "HASH" containing a set of name/value pairs of
       the new values to be applied to configuration, or "undef" if there are
       no changes to configuration.

   config_get
           $dialog->config_get(
               Padre::Current->config->meta('identity_name')
           );

       The "config_get" method fetches a single configuration value form a the
       public dialog control.

       It takes a single parameter, which should be the Padre::Config::Setting
       metadata object for the configuration preference to fetch.

       Successfully getting a value is by no means certain, there can be a
       number of different reasons why no value may be returned. These
       include:

       The lack of a public getter method for the form control
       The form control being disabled (i.e. not $control->IsEnabled)
       The form control returning "undef" (which native Wx controls won't)
       The form control being incompatible with the config data type

       Returns a simple defined scalar value suitable for being passed "set"
       in Padre::Config on success, or "undef" if no value can be found.

   config_set
           $dialog->config_set(
               Padre::Current->config->meta('identity_name'),
               'My Name',
           );

       The "config_set" method applies a simple scalar value to a form
       control.

       It takes two parameters, a Padre::Config::Setting metadata object for
       the configuration preference to load, and a value to load into the form
       control.

       Returns true if the value was loaded into the form control, false if
       the form control was unknown or not compatible with the preference, or
       "undef" if the form control does not exist at all in the dialog.

COPYRIGHT & LICENSE
       Copyright 2008-2012 The Padre development team as listed in Padre.pm.

       This program is free software; you can redistribute it and/or modify it
       under the same terms as Perl 5 itself.

       The full text of the license can be found in the LICENSE file included
       with this module.



perl v5.14.2                      2012-04-19      Padre::Wx::Role::Config(3pm)