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

FreeBSD Manual Pages

  
 
  

home | help
Prima::VB::VBLoader(3)User Contributed Perl DocumentatioPrima::VB::VBLoader(3)

NAME
       Prima::VB::VBLoader - Visual Builder file loader

DESCRIPTION
       The module provides functionality for loading resource files, created
       by Visual Builder. After	the successful load, the newly created window
       with all	children is returned.

SYNOPSIS
       The simple way to use the loader	is as that:

	       use Prima qw(Application);
	       use Prima::VB::VBLoader;
	       Prima::VBLoad( './your_resource.fm',
		       Form1 =>	{ centered => 1	},
	       )-> execute;

       A more complicated but more proof code can be met in the	toolkit:

	       use Prima qw(Application);
	       eval "use Prima::VB::VBLoader"; die "$@\n" if $@;
	       $form = Prima::VBLoad( $fi,
		       'Form1'	   => {	visible	=> 0, centered => 1},
	       );
	       die "$@\n" unless $form;

       All form	widgets	can be supplied	with custom parameters,	all together
       combined	in a hash of hashes and	passed as the second parameter to
       "VBLoad()" function.  The example above supplies	values for "::visible"
       and "::centered"	to "Form1" widget, which is default name of a form
       window created by Visual	Builder. All other widgets are accessible by
       their names in a	similar	fashion; after the creation, the widget
       hierarchy can be	accessed in the	standard way:

	       $form = Prima::VBLoad( $fi,
		       ....
		       'StartButton' =>	{
			       onMouseOver => sub { die	"No start buttons here\n" },
		       }
	       );
	       ...
	       $form-> StartButton-> hide;

       In case a form is to be included	not from a fm file but from other data
       source, AUTOFORM_REALIZE	call can be used to transform perl array into
       set of widgets:

	       $form = AUTOFORM_REALIZE( [ Form1 => {
		       class   => 'Prima::Window',
		       parent  => 1,
		       profile => {
			       name => 'Form1',
			       size => [ 330, 421],
		       }], {});

       Real-life examples are met across the toolkit; for instance,
       Prima/PS/setup.fm dialog	is used	by "Prima::PS::Setup".

API
   Methods
       check_version HEADER
	   Scans HEADER, - the first line of a .fm file	for version info.
	   Returns two scalars - the first is a	boolean	flag, which is set to
	   1 if	the file can be	used and loaded, 0 otherwise. The second
	   scalar is a version string.

       GO_SUB SUB [ @EXTRA_DATA	]
	   Depending on	value of boolean flag
	   "Prima::VB::VBLoader::builderActive"	performs the following:	if it
	   is 1, the SUB text is returned as is.  If it	is 0, evaluates	it in
	   "sub{}" context and returns the code	reference.  If evaluation
	   fails, EXTRA_DATA is	stored in "Prima::VB::VBLoader::eventContext"
	   array and the exception is re-thrown.
	   "Prima::VB::VBLoader::builderActive"	is an internal flag that helps
	   the Visual Builder use the module interface without actual SUB
	   evaluation.

       AUTOFORM_REALIZE	WIDGETS, PARAMETERS
	   WIDGETS is an array reference that contains evaluated data of the
	   read	content	of .fm file ( its data format is preserved).
	   PARAMETERS is a hash	reference with custom parameters passed	to
	   widgets during creation. The	widgets	are distinguished by the
	   names.  Visual Builder ensures that no widgets have equal names.

	   "AUTOFORM_REALIZE" creates the tree of widgets and returns the root
	   window, which is usually named "Form1". It automatically resolves
	   parent-child	relations, so the order	of WIDGETS does	not matter.
	   Moreover, if	a parent widget	is passed as a parameter to a children
	   widget, the parameter is deferred and passed	after the creation
	   using "::set" call.

	   During the parsing and creation process internal notifications can
	   be invoked.	These notifications (events) are stored	in .fm file
	   and usually provide class-specific loading instructions. See	Events
	   for details.

       AUTOFORM_CREATE FILENAME, %PARAMETERS
	   Reads FILENAME in .fm file format, checks its version, loads, and
	   creates widget tree.	Upon successful	load the root widget is
	   returned. The parsing and creation is performed by calling
	   "AUTOFORM_REALIZE". If loading fails, "die()" is called.

       Prima::VBLoad FILENAME, %PARAMETERS
	   A wrapper around "AUTOFORM_CREATE", exported	in "Prima" namespace.
	   FILENAME can	be specified either as a file system path name,	or as
	   a relative module name. In a	way,

		   Prima::VBLoad( 'Module::form.fm' )

	   and

		   Prima::VBLoad(
			   Prima::Utils::find_image( 'Module' 'form.fm'))

	   are identical. If the procedure finds that FILENAME is a relative
	   module name,	it calls "Prima::Utils::find_image" automatically. To
	   tell	explicitly that	FILENAME is a file system path name, FILENAME
	   must	be prefixed with "<" symbol ( the syntax is influenced by
	   "CORE::open"	).

	   %PARAMETERS is a hash with custom parameters	passed to widgets
	   during creation. The	widgets	are distinguished by the names.
	   Visual Builder ensures that no widgets have equal names.

	   If the form file loaded successfully, returns the form object
	   reference.  Otherwise, "undef" is returned and the error string is
	   stored in $@	variable.

   Events
       The events, stored in .fm file are called during	the loading process.
       The module provides no functionality for	supplying the events during
       the load. This interface	is useful only for developers of Visual
       Builder - ready classes.

       The events section is located in	"actions" section of widget entry.
       There can be more than one event	of each	type, registered to different
       widgets.	 NAME parameter	is a string with name of the widget; INSTANCE
       is a hash, created during load for every	widget provided	to keep
       internal	event-specific or class-specific data there. "extras" section
       of widget entry is present there	as an only predefined key.

       Begin NAME, INSTANCE
	   Called upon beginning of widget tree	creation.

       FormCreate NAME,	INSTANCE, ROOT_WIDGET
	   Called after	the creation of	a form,	which reference	is contained
	   in ROOT_WIDGET.

       Create NAME, INSTANCE, WIDGET.
	   Called after	the creation of	the widget. The	newly created widget
	   is passed in	WIDGET

       Child NAME, INSTANCE, WIDGET, CHILD_NAME
	   Called before child of WIDGET is created with CHILD_NAME as name.

       ChildCreate NAME, INSTANCE, WIDGET, CHILD_WIDGET.
	   Called after	child of WIDGET	is created; the	newly created widget
	   is passed in	CHILD_WIDGET.

       End NAME, INSTANCE, WIDGET
	   Called after	the creation of	all widgets is finished.

FILE FORMAT
       The idea	of format of .fm file is that is should	be evaluated by	perl
       "eval()"	call without special manipulations, and	kept as	plain text.
       The file	begins with a header, which is a #-prefixed string, and
       contains	a signature, version of	file format, and version of the
       creator of the file:

	       # VBForm	version	file=1 builder=0.1

       The header can also contain additional headers, also prefixed with #.
       These can be used to tell the loader that another perl module is	needed
       to be loaded before the parsing;	this is	useful,	for example, if	a
       constant	is declared in the module.

	       # [preload] Prima::ComboBox

       The main	part of	a file is enclosed in "sub{}" statement.  After
       evaluation, this	sub returns array of paired scalars, where each	first
       item is a widget	name and second	item is	hash of	its parameters and
       other associated	data:

	       sub
	       {
		       return (
			       'Form1' => {
				       class   => 'Prima::Window',
				       module  => 'Prima::Classes',
				       parent => 1,
				       code   => GO_SUB('init()'),
				       profile => {
					       width =>	144,
					       name => 'Form1',
					       origin => [ 490,	412],
					       size => [ 144, 100],
			       }},
		       );
	       }

       The hash	has several predefined keys:

       actions HASH
	   Contains hash of events. The	events are evaluated via "GO_SUB"
	   mechanism and executed during creation of the widget	tree. See
	   Events for details.

       code STRING
	   Contains a code, executed before the	form is	created.  This key is
	   present only	on the root widget record.

       class STRING
	   Contains name of a class to be instantiated.

       extras HASH
	   Contains a class-specific parameters, used by events.

       module STRING
	   Contains name of perl module	that contains the class. The module
	   will	be "use"'d by the loader.

       parent BOOLEAN
	   A boolean flag; set to 1 for	the root widget	only.

       profile HASH
	   Contains profile hash, passed as parameters to the widget during
	   its creation. If custom parameters were passed to
	   "AUTOFORM_CREATE", these are	coupled	with "profile" ( the custom
	   parameters take precedence )	before passing to the "create()" call.

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

SEE ALSO
       Prima, VB

perl v5.24.1			  2017-02-28		Prima::VB::VBLoader(3)

NAME | DESCRIPTION | SYNOPSIS | API | FILE FORMAT | AUTHOR | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Prima::VB::VBLoader&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help