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-2013 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.