Man Linux: Main Page and Category List

NAME

       Prima::VB::Classes - Visual Builder widgets and types

DESCRIPTION

       Visual Builder is designed without a prior knowledge of the widget
       classes that would be contained in its widget palette.  Instead, it
       provides a registration interface for new widgets and their specific
       properties.

       This document describes API, provided by the builder, and the widget
       interface. Through the document, widget or widget class mean not the
       original widget or class, but their representatives.

USAGE

       The widget must provide specific methods to cooperate with the builder.
       It is not required, however, to contain these methods in its base
       module or package; it can delegate its representation to another,
       usually very light class, which is used by the builder.

       Such a class must be derived from "Prima::VB::Object", which provides
       base functionality. One of basic features here is overloading of
       property change method. Since the user can change any property
       interactively, the class can catch the properties of interest by
       declaring "prf_XXX" method, where XXX is the property name.
       "Prima::VB::Widget" declares set of these methods, assuming that a
       widget would repaint when, for example, its "color" or "font"
       properties change.

       The hierarchy of VB classes mimics the one of the core toolkit classes,
       but this is a mere resemblance, no other dependencies except the names
       are present. The hierarchy is as follows:

               Prima::VB::Object   Prima::Widget
                       Prima::VB::Component
                               Prima::VB::Drawable
                                       Prima::VB::Widget
                                               Prima::VB::Control
                                                       Prima::VB::Window

       NB: "Prima::VB::CoreClasses" extends the hierarchy to the full set of
       default widget palette in the builder. This module is not provided with
       documentation though since its function is obvious and its code is
       trivial.

       Since the real widgets are used in the interaction with the builder,
       their properties are not touched when changed by the object inspector
       or otherwise. The widgets keep the set of properties in a separated
       hash. The properties are accessible by "prf" and "prf_set" methods.

       A type object is a class used to represent a particular type of
       property in object inspector window in the builder.  The type objects,
       like the widget classes, also are not hard-coded. The builder presents
       a basic set of the type objects, which can be easily expanded.  The
       hierarchy ( incomplete ) of the type objects classes is as follows:

               Prima::VB::Types::generic
                       Prima::VB::Types::bool
                       Prima::VB::Types::color
                       Prima::VB::Types::point
                       Prima::VB::Types::icon
                       Prima::VB::Types::Handle
                       Prima::VB::Types::textee
                               Prima::VB::Types::text
                               Prima::VB::Types::string
                                       Prima::VB::Types::char
                                       Prima::VB::Types::name
                                       Prima::VB::Types::iv
                                               Prima::VB::Types::uiv

       The document does not describe the types, since their function can be
       observed at runtime in the object inspector.  Only
       "Prima::VB::Types::generic" API is documented.

Prima::VB::Object

   Properties
       class STRING
           Selects the original widget class. Create-only property.

       creationOrder INTEGER
           Selects the creation order of the widget.

       module STRING
           Selects the module that contains the original widget class. Create-
           only property.

       profile HASH
           Selects the original widget profile. Create-only property.  Changes
           to profile at run-time performed by "prf_set" method.

   Methods
       act_profile
           Returns hash of callbacks to be stored in the form file and
           executed by "Prima::VB::VBLoader" when the form file is loaded.
           The hash keys are names of VBLoader events and values - strings
           with code to be eval’ed. See "Events" in Prima::VB::VBLoader for
           description and format of the callbacks.

           Called when the builder writes a form file.

       add_hooks @PROPERTIES
           Registers the object as a watcher to set of PROPERTIES.  When any
           object changes a property listed in the hook record, "on_hook"
           callback is triggered.

           Special name 'DESTROY' can be used to set a hook on object
           destruction event.

       ext_profile
           Returns a class-specific hash, written in a form file.  Its use is
           to serve as a set of extra parameters, passed from the builder to
           "act_profile" events.

       prf_set %PROIFLE
           A main method for setting a property of an object.  PROFILE keys
           are property names, and value are property values.

       prf_adjust_default PROFILE, DEFAULT_PROFILE
           DEFAULT_PROFILE is a result of "profile_default" call of the real
           object class. However, not all properties usually are exported to
           the object inspector. "prf_adjust_default" deletes the unneeded
           property keys from PROFILE hash.

       prf_delete @PROPERTIES
           Removes PROPERTIES from internal properties hash.  This action
           results in that the PROPERTIES in the object inspector are set back
           to their default values.

       prf_events
           Returns hash of a class-specific events. These appear in the object
           inspector on "Events" page. The hash keys are event names; the hash
           values are default code pieces, that describe format of the event
           parameters. Example:

                   sub prf_events { return (
                           $_[0]-> SUPER::prf_events,
                           onSelectItem  => 'my ( $self, $index, $selectState) = @_;',
                   )}

       prf @PROPERTIES
           Maps array of PROPERTIES names to their values. If called in scalar
           context, returns the first value only; if in array context, returns
           array of property values.

       prf_types
           Returns an anonymous hash, where keys are names of the type class
           without "Prima::VB::Types::" prefix, and values are arrays of
           property names.

           This callback returns an inverse mapping of properties by the
           types.

       prf_types_add PROFILE1, PROFILE2
           Adds PROFILE2 content to PROFILE1. PROFILE1 and PROFILE2 are hashes
           in format of result of "prf_types" method.

       prf_types_delete PROFILE, @NAMES
           Removes @NAMES from PROFILE. Need to be called if property type if
           redefined through the inheritance.

       remove_hooks @PROPERTIES
           Cancels watch for set of PROPERTIES.

   Events
       on_hook NAME, PROPERTY, OLD_VALUE, NEW_VALUE
           Called for all objects, registered as watchers by "add_hooks" when
           PROPERTY on object NAME is changed from OLD_VALUE to NEW_VALUE.
           Special PROPERTY 'DESTROY' hook is called when object NAME is
           destroyed.

Prima::VB::Component

   Properties
       marked MARKED , EXCLUSIVE
           Selects marked state of a widget. If MARKED flag is 1, the widget
           is selected as marked. If 0, it is selected as unmarked.  If
           EXCLUSIVE flag is set to 1, then all marked widgets are unmarked
           before the object mark flag is set.

       sizeable BOOLEAN
           If 1, the widget can be resized by the user.  If 0, in can only be
           moved.

       mainEvent STRING
           Selects the event name, that will be opened in the object inspector
           when the user double clicks on the widget.

   Methods
       common_paint CANVAS
           Draws selection and resize marks on the widget if it is in the
           selected state. To be called from all "on_paint" callbacks.

       get_o_delta
           Returns offset to the owner widget. Since the builder does not
           insert widgets in widgets to reflect the user-designed object
           hierarchy, this method is to be used to calculate children widgets
           relative positions.

       xy2part X, Y
           Maps X, Y point into part of widget. If result is not equal to
           'client' string, the event in X, Y point must be ignored.

       iterate_children SUB, @ARGS
           Traverses all children widget in the hierarchy, calling SUB routine
           with widget, self, and @ARGS parameters on each.

       altpopup
           Invokes an alternative, class-specific popup menu, if present.  The
           popup object must be named 'AltPopup'.

   Events
       Load
           Called when the widget is loaded from a file or the clipboard.

Prima::VB::Types::generic

       Root of all type classes.

       A type class can be used with and without object instance. The
       instantiated class contains reference to ID string, which is a property
       name that the object presents in the object inspector, and WIDGET,
       which is the property applied to. When the object inspector switches
       widgets, the type object is commanded to update the references.

       A class must also be usable without object instance, in particular, in
       "write" method. It is called to export the property value in a storable
       format as a string, better as a perl-evaluable expression.

   Methods
       new CONTAINER, ID, WIDGET
           Constructor method. CONTAINER is a panel widget in the object
           inspector, where the type object can insert property value selector
           widgets.

       renew ID, WIDGET
           Resets property name and the widget.

       quotable STRING
           Returns quotable STRING.

       printable STRING
           Returns a string that can be stored in a file.

   Callbacks
       change
           Called when the widget property value is changed.

       change_id
           Called when the property name ( ID ) is changed.  The type object
           may consider update its look or eventual internal variables on this
           event.

       get Returns property value, based on the selector widgets value.

       open
           Called when the type object is to be visualized first time.  The
           object must create property value selector widgets in the
           "{container}" panel widget.

       preload_modules
           Returns array of strings of modules, needed to be pre-loaded before
           a form file with type class-specific information can be loaded.
           Usually it is used when "write" method exports constant values,
           which are defined in another module.

       set DATA
           Called when a new value is set to the widget property by means
           other than the selector widgets, so these can be updated. DATA is
           the property new value.

       valid
           Checks internal state of data and returns a boolean flag, if the
           type object data can be exported and set to widget profile.

       write CLASS, ID, DATA
           Called when DATA is to be written in form.  "write" must return
           such a string that can be loaded by "Prima::VB::VBLoader" later.

AUTHOR

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

SEE ALSO

       VB, Prima::VB::VBLoader, Prima::VB::CfgMaint.