NAME

       Prima::VB::CfgMaint - maintains visual builder widget palette configuration.

DESCRIPTION

       The module is used by the Visual Builder and "cfgmaint" programs, to maintain the Visual
       Builder widget palette. The installed widgets are displayed in main panel of the Visual
       Builder, and can be maintained by "cfgmaint".

USAGE

       The Visual Builder widget palette configuration is contained in two files - the system-
       wide "Prima::VB::Config" and the user "~/.prima/vbconfig". The user config file take the
       precedence when loaded by the Visual Builder. The module can select either configuration
       by assigning $systemWide boolean property.

       The widgets are grouped in pages, which are accessible by names.

       New widgets can be added to the palette by calling "add_module" method, which accepts a
       perl module file as its first parameter. The module must conform to the VB-loadable
       format.

FORMAT

       This section describes format of a module with VB-loadable widgets.

       The module must define a package with same name as the module.  In the package, "class"
       sub must be declared, that returns an array or paired scalars, where each first item in a
       pair corresponds to the widget class and the second to a hash, that contains the class
       loading information, and must contain the following keys:

       class STRING
           Name of the VB-representation class, which represents the original widget class in the
           Visual Builder. This is usually a lightweight class, which does not contain all
           functionality of the original class, but is capable of visually reflecting changes to
           the class properties.

       icon PATH
           Sets an image file, where the class icon is contained.  PATH provides an extended
           syntax for indicating a frame index, if the image file is multiframed: the frame index
           is appended to the path name with ":" character prefix, for example:
           "NewWidget::icons.gif:2".

       module STRING
           Sets the module name, that contains "class".

       page STRING
           Sets the default palette page where the widget is to be put.  The current
           implementation of the Visual Builder provides four pages:
           "General,Additional,Sliders,Abstract". If the page is not present, new page is
           automatically created when the widget class is registered.

       RTModule STRING
           Sets the module name, that contains the original class.

       The reader is urged to explore Prima::VB::examples::Widgety file, which contains an
       example class "Prima::SampleWidget", its VB-representation, and a property
       "lineRoundStyle" definition example.

API

   Methods
       add_module FILE
           Reads FILE module and loads all VB-loadable widgets from it.

       classes
           Returns string declaration of all registered classes in format of "classes"
           registration procedure ( see "FORMAT" ).

       open_cfg
           Loads class and pages information from either a system-wide or a user configuration
           file.  If succeeds, the information is stored in @pages and %classes variables ( the
           old information is lost ) and returns 1. If fails, returns 0 and string with the error
           explanation; @pages and %classes content is undefined.

       pages
           Returns array of page names

       read_cfg
           Reads information from both system-wide and user configuration files, and merges the
           information. If succeeds, returns 1. If fails, returns 0 and string with the error
           explanation.

       reset_cfg
           Erases all information about pages and classes.

       write_cfg
           Writes either the system-wide or the user configuration file.  If $backup flag is set
           to 1, the old file renamed with ".bak" extension.  If succeeds, returns 1. If fails,
           returns 0 and string with the error explanation.

FILES

       Prima::VB::Config.pm, "~/.prima/vbconfig".

AUTHOR

       Dmitry Karasik, <dmitry@karasik.eu.org>.

SEE ALSO

       VB, cfgmaint, Prima::VB::examples::Widgety.