NAME

XMLBuilder - Build Win32::GUIs using XML.

SYNOPSIS

use Win32::GUI::XMLBuilder;

my $gui = Win32::GUI::XMLBuilder->new({file=>"file.xml"});
my $gui = Win32::GUI::XMLBuilder->new(*DATA);

Win32::GUI::Dialog;

sub test {
 $gui->{Status}->Text("testing 1 2 3..");
}

...

__END__
<GUI>

..
</GUI>

DEPENDENCIES

XML::Twig
Win32::GUI

DESCRIPTION

This module allows Win32::GUIs to be built using XML. For examples on usage please look in samples/ directory.

XML SYNTAX

XMLBuilder will parse an XML file or string that contains elements that describe a Win32::GUI object.

All XML documents must be enclosed in <GUI>..</GUI> elements and each separate GUI window must be enclosed in <Window>..</Window> elements. To create a N-tier window system one might use a construction similar to: -

<GUI>
 <Window name="W_1">
  ...
 </Window>
 <Window name="W_2">
  ...
 </Window>
 <Window name="W_N">
  ...
 </Window>
</GUI>

ATTRIBUTES

Elements can additionally be supplemented with attributes that describe its corresponding Win32::GUI object's properties such as top, left, height and width. These properties usually include those provided as standard in each Win32::GUI class. I.e.

<Window height="200" width="200" title="My Window"/>

Elements that require referencing in your code should be given a name attribute. An element with attribute: -

<Button name="MyButton"/>

can be called as $gui->{'MyButton'} and event subroutines called using MyButton_Click. From within an XML string the element must be called by $self->{'MyButton'}.

Attributes can contain Perl code or variables and generally any attribute that contains the variable '$self' or starts with 'exec:' will be evaluated. This is useful when one wants to create dynamically sizing windows: -

<Window name='W'
 left='0' top='0' 
 width='400' height='200' 
 style='exec:WS_CLIPCHILDREN|WS_OVERLAPPEDWINDOW'
>
 <StatusBar name='S' 
  left='0' top='$self->{W}->ScaleHeight-$self->{S}->Height' 
  width='$self->{W}->ScaleWidth' height='$self->{S}->Height'
 />
</Window>

NOTE: pos and size attributes are supported but converted to top, left, height and width attributes on parsing. I suggest using the attribute dim='left,top,width,height' instead (not an array but an list with brackets).

AUTO-RESIZING

Win32::GUI::XMLBuilder will autogenerate an onResize NEM method by reading in values for top, left, height and width. This will work sufficiently well provided you use values that are dynamic such as $self->{PARENT_WIDGET}->Width, $self->{PARENT_WIDGET}->Height for width, height attributes respectively when creating new widget elements.

NEM Events

NEM events are supported. When specifying a NEM event such as onClick one must use $self syntax to specify current Win32::GUI::XMLBuilder object in anonymous subroutines. An attribute of notify='1' is added automatically when an NEM event is called. One can alo specify other named subroutines by name, but do not prefix with an ampersand! i.e.

onClick='my_sub' [CORRECT]
onClick='&my_sub' [INCORRECT]

AUTO WIDGET NAMING

Win32::GUI::XMLBuilder will autogenerate a name for a wiget if a 'name' attribute is not provided. The current naming convention is Widget_Class_N where N is a number. For example Button_1, Window_23, etc...

ENVIRONMENT VARIABLES

WIN32GUIXMLBUILDER_DEBUG

Setting this to 1 will produce logging.

METHODS

new({file=>$file}) or new($xmlstring)

SUPPORTED WIDGETS - ELEMENTS

Most Win32::GUI widgets are supported and general type widgets can added without any modification being added to this module.

<PreExec>

The <PreExec> element is parsed before GUI construction and is useful for defining subroutines and global variables. Code is wrapped in a { package main; no strict; .. } so that if subroutines are created they can contain variables in your program including Win32::GUI::XMLBuilder instances. The current Win32::GUI::XMLBuilder instance can also be accessed outside subroutines as $self.

Since you may need to use a illegal XML characters within this element such as

<  less than      (&lt;) 
>  greater than   (&gt;)
&  ampersand      (&amp;)
'  apostrophe     (&apos;)
"  quotation mark (&quot;)

you can use the alternative predefined entity reference or enclose this data in a "<![CDATA[" "]]>" section. Please look at the samples and read http://www.w3schools.com/xml/xml_cdata.asp.

The <PreExec> element was previously called as <Script> and is deprecated. The <Script> tage remains only for backward compatibility and will be removed in a later release.

<PostExec>

The <PostExec> element is parsed after GUI construction and allows code to be included at the end of an XML file. It otherwise behaves exactly the same as <PreExec> and can be used to place _Resize subroutines.

<Icon>

The <Icon> element allows you to specify an Icon for your program.

<Icon file="myicon.ico" name='MyIcon' />

The <Bitmap> element allows you to specify an Bitmap for your program.

<Bitmap file="bitmap.bmp" name='Image' />

The <Cursor> element allows you to specify an Cursor for your program.

<Icon file="mycursor.cur" name='Cursor' />

<ImageList>

<ImageList name='IL' width='16' height='16' maxsize='10'>
 <Item bitmap='one.bmp'/>
 <Item bitmap='two.bmp'/>
 <Item bitmap='$self->{Bitmap}'/>
</ImageList>

<Font>

Allows you to create a font for use in your program.

<Font name='Bold' 
 size='8' 
 face='Arial' 
 bold='1' 
 italic='0'
/>

You might call this in a label element using something like this: -

<label 
 text='some text' 
 font='$self->{Bold}' 
 ... 
/>.

<Class>

You can create a <Class> element,

<Class name='MyClass' icon='$self->{MyIcon}'/> 

that can be applied to a <Window .. class='$self->{MyClass}'>. The name of a class must be unique over all instances of Win32::GUI::XMLBuilder instances!

<Menu>

Creates a menu system. The amount of '>'s prefixing a text label specifies the menu items depth. A value of text '-' (includes '>-', '>>-', etc) creates a separator line. To access named menu items one must use the menu widgets name, i.e. $gui->{PopupMenu}->{SelectAll}, although one can access an event by its name, i.e. SelectAll_Click. One can also use NEM events directly as attributes such as onClick, etc..

<Menu name='PopupMenu'>
 <Item text='ContextMenu'/>
 <Item  name='OnEditCut' text='>Cut'/>
 <Item name='OnEditCopy' text='>Copy'/>
 <Item name='OnEditPaste' text='>Paste'/>
 <item text='>-' />
 <Item name='SelectAll' text='>Select All'/>
 <item text='>-' />
 <Item name='Mode' text='>Mode' checked='1'/>
</Menu>

See the menus.xml example in the samples/ directory.

<Window>

The <Window> element creates a top level widget. In addition to standard Win32::GUI::Window attributes it also has a 'show=n' attribute. This instructs XMLBuilder to give the window a Show(n) command on invocation.

<Window show='0' ... />

NOTE: Since the onResize event is defined automatically for the this element one must set the attribute 'eventmodel' to 'both' to allow <Window_Name>_Event events to be caught!

<TabFrame>

A Tab strip can be created using the following structure: -

<TabFrame ...>
 <Item name='P0' text='Zero'>
  <Label text='Tab 1' .... />
 </Item>
 <Item name='P1' text='One'>
  <Label text='Tab 2' .... />
   ..other elements, etc...
 </Item>
</TabFrame>

See the wizard.pl example in the samples/ directory.

<TreeView>

Creates a TreeView. These can be nested deeply using the sub element <Item>. Please look at the treeview.pl example in the samples/ directory.

<TreeView ..>
 <Item .. />
  <Item ..>
   <Item .. />
   <Item .. />
    etc...
  </item>
 ...
</TreeView>

<Combobox>

Generate a combobox with drop down items specified with the <Items> elements. In addition to standard attributes for Win32::GUI::Combobox there is also a 'dropdown' attribute that automatically sets the 'style' to 'exec:WS_VISIBLE|0x3|WS_VSCROLL|WS_TABSTOP'. In 'dropdown' mode an <Item> element has the additional attribute 'default'.

<Listbox>

Generate a listbox with drop down items specified with the <Items> elements. In addition to standard attributes for Win32::GUI::Listbox there is also a 'dropdown' attribute that automatically sets the 'style' to 'exec:WS_CHILD|WS_VISIBLE|1'. In 'dropdown' mode an <Item> element has the additional attribute 'default'.

<Rebar>

See rebar.xml example in samples/ directory.

Generic Elements

Any widget not explicitly mentioned above can be generated by using its name as an element id. For example a Button widget can be created using: -

<Button name='B' 
 text='Push Me' 
 left='20' top='0' 
 width='80' height='20'
/>

cpanm Win32::GUI::XMLBuilder

perl -MCPAN -e shell
install Win32::GUI::XMLBuilder