Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Prima::VB::Classes(3) User Contributed Perl DocumentationPrima::VB::Classes(3)

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

       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

       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.

       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

       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

       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:


       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.

       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.

	   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.

	   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.

	   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.

	   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

       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.

	   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

       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

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

       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.

	   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.

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

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

       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.

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

       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.

	   Called when the widget property value is changed.

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

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

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

	   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.

	   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.

       Dmitry Karasik, <>.

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

perl v5.24.1			  2017-05-15		 Prima::VB::Classes(3)

NAME | DESCRIPTION | USAGE | Prima::VB::Object | Prima::VB::Component | Prima::VB::Types::generic | AUTHOR | SEE ALSO

Want to link to this manual page? Use this URL:

home | help