NAME
XUL::Gui - render cross platform gui applications with firefox from perl
VERSION
version 0.21
this module is under active development, interfaces may change.
this code is currently in beta, use in production environments at your own risk
the code will be considered production ready, and interfaces finalized at version 0.50
this documentation is a work in progress
SYNOPSIS
use XUL::Gui;
display Label 'hello, world!';
# short enough? s/Label/P/ for bonus points
use XUL::Gui;
display Window title => "XUL::Gui's long hello", minwidth=>300,
GroupBox(
Caption('XUL'),
Button( label=>'click me', oncommand=> sub {shift->label = 'ouch'} ),
Button( id=>'btn',
label=>'automatic id registration',
oncommand=>sub{
$ID{btn}->label = 'means no more variable clutter';
$ID{txt}->value = 'and makes cross tag updates easy';
}),
Button( type=>'menu', label=>'menu button',
MenuPopup map {MenuItem label=>$_} qw/first second third/
),
TextBox( id=>'txt', FILL ),
ProgressMeter(mode=>'undetermined'),
),
GroupBox(
Caption('HTML too'),
TABLE( border=>1, TR map {TD $_} 'one', I('two'), B('three'), U('four'), SUP('five') ),
HR,
P('all the HTML tags are in CAPS'),
);
DESCRIPTION
this module exposes the entire functionality of mozilla firefox's rendering engine to perl by providing all of the XUL and HTML tags as functions and allowing you to interact with those objects directly from perl. gui applications created with this toolkit are cross platform, fully support CSS styling, inherit firefox's rich assortment of web technologies (browser, canvas and video tags, flash and other plugins), and are even easier to write than HTML.
this module is written in pure perl, and only depends upon core modules, making it easy to distribute your application.
all XUL and HTML objects in perl are exact mirrors of their javascript counterparts and can be acted on as such. for anything not written in this document or XUL::Gui::Manual, developer.mozilla.com is the official source of documentation:
http://www.hevanet.com/acorbin/xul/top.xul - XUL periodic table
gui's created with this module are event driven. an arbitrarily complex (and runtime mutable) object tree is passed to display
, which then creates the gui in firefox and starts the event loop. display
will wait for and respond to events until the quit
function is called, or the user closes the firefox window.
all of javascript's event handlers are available, and can be written in perl (normally) or javascript (for handlers that need to be very fast such as image rollovers with onmouseover or the like). this is not to say that perl side handlers are slow, but with rollovers and fast mouse movements, sometimes there is mild lag due to protocol overhead.
the goal of this module is to make gui development as easy as possible. XUL's widgets and nested design structure gets us most of the way there, and this module with its light weight syntax, and "Do What I Mean" nature hopefully finishes the job. everything has sensible defaults with minimal boilerplate, and nested design means a logical code flow that isn't littered with variables. now you can focus on your gui's design and functionality, and hopefully not on the deficiencies of your toolkit. if XUL::Gui doesn't get you all the way there yet, give it time, I'm still working on it.
tags
all tags (XUL
, HTML
, user defined widgets, and the display
function) are parsed the same way, and can fit into one of four templates
HR() is <html:hr />
B('some bold text') is <html:b>some bold text<html:b/>
in the special case of a tag with one argument, which is not another tag, that argument is added to that tag as a text node. this is mostly useful for HTML tags, but works with XUL as well
Label( value=>'some text', style=>'color: red' ) is <label value="some text" style="color: red;" />
Hbox( id=>'mybox', Label('hello'), B('world'), style=>'border: 1px solid black')
<hbox id="mybox" style="border: 1px solid black;"> <label><textnode value="hello"></label> <html:b>world</html:b> </hbox>
unlike XML based XUL, attribute pairs and children can be mixed in any order, but should probably be kept at the front for readability
setting the 'id' attribute names the object in the %ID
hash. otherwise an auto generated name matching /^xul_\d+$/
is used.
$object = Button( id=>'btn', label=>'OK' );
# $ID{btn} == $object
any tag attribute name that matches /^on/
is an event handler (onclick, onfocus....), and expects a sub{...}
(perl event handler) or function q{...}
(javascript event handler).
perl event handlers get passed a reference to themselves, and an event object
Button( label=>'click me', oncommand=> sub {
my ($self, $event) = @_;
$self->label = $event->type;
})
javascript event handlers have event
and this
set for you
Button( label=>'click me', oncommand=> function q{
this.label = event.type;
})
any attribute with a name that doesn't match /^on/ that has a code ref value is added to the object as a method
EXPORT
all functions listed here are exported by default, this may change in the future
all XUL tags: (also exported as Titlecase)
Action ArrowScrollBox Assign BBox Binding Bindings Box Broadcaster BroadcasterSet
Browser Button Caption CheckBox ColorPicker Column Columns Command CommandSet Conditions
Content DatePicker Deck Description Dialog DialogHeader DropMarker Editor Grid Grippy
GroupBox HBox IFrame Image Key KeySet Label ListBox ListCell ListCol ListCols ListHead
ListHeader ListItem Member Menu MenuBar MenuItem MenuList MenuPopup MenuSeparator
Notification NotificationBox Observes Overlay Page Panel Param PopupSet PrefPane PrefWindow
Preference Preferences ProgressMeter Query QuerySet Radio RadioGroup Resizer RichListBox
RichListItem Row Rows Rule Scale Script ScrollBar ScrollBox ScrollCorner Separator Spacer
SpinButtons Splitter Stack StatusBar StatusBarPanel StringBundle StringBundleSet Tab TabBox
TabPanel TabPanels Tabs Template TextBox TextNode TimePicker TitleBar ToolBar ToolBarButton
ToolBarGrippy ToolBarItem ToolBarPalette ToolBarSeparator ToolBarSet ToolBarSpacer
ToolBarSpring ToolBox ToolTip Tree TreeCell TreeChildren TreeCol TreeCols TreeItem TreeRow
TreeSeparator Triple VBox Where Window Wizard WizardPage
all HTML tags: (also exported as html_lowercase)
A ABBR ACRONYM ADDRESS APPLET AREA AUDIO B BASE BASEFONT BDO BGSOUND BIG BLINK BLOCKQUOTE
BODY BR BUTTON CANVAS CAPTION CENTER CITE CODE COL COLGROUP COMMENT DD DEL DFN DIR DIV DL DT
EM EMBED FIELDSET FONT FORM FRAME FRAMESET H1 H2 H3 H4 H5 H6 HEAD HR HTML I IFRAME ILAYER IMG
INPUT INS ISINDEX KBD LABEL LAYER LEGEND LI LINK LISTING MAP MARQUEE MENU META MULTICOL NOBR
NOEMBED NOFRAMES NOLAYER NOSCRIPT OBJECT OL OPTGROUP OPTION P PARAM PLAINTEXT PRE Q RB RBC RP
RT RTC RUBY S SAMP SCRIPT SELECT SMALL SOURCE SPACER SPAN STRIKE STRONG STYLE SUB SUP TABLE
TBODY TD TEXTAREA TFOOT TH THEAD TITLE TR TT U UL VAR VIDEO WBR XML XMP
utility: zip mapn apply trace toggle
gui: display widget attribute extends quit alert dialog function gui XUL
constants: FLEX FIT FILL SCROLL MIDDLE
pragma: buffered now cached noevents delay doevents
internal: tag object genid
FUNCTIONS
utility functions
mapn {CODE} NUMBER LIST
-
map over n elements at a time in
@_
with$_ == $_[0]
print mapn {$_ % 2 ? "@_" : " [@_] "} 3 => 1..20; > 1 2 3 [4 5 6] 7 8 9 [10 11 12] 13 14 15 [16 17 18] 19 20
zip LIST of ARRAYREF
-
%hash = zip [qw/a b c/], [1..3];
apply {CODE} LIST
-
apply a function to a list and return that list
print join ", " => apply {s/$/ one/} "this", "and that"; > this one, and that one
toggle TARGET OPT1 OPT2
-
alternate a variable between two states
toggle $state => 0, 1;
constants
FLEX flex => 1
FILL flex => 1, align =>'stretch'
FIT sizeToContent => 1
SCROLL style => 'overflow: auto'
MIDDLE align => 'center', pack => 'center'
each is a function that returns its constant, prepended to
its arguments, thus the following are both valid:
Box FILL pack=>'end';
Box FILL, pack=>'end';
gui functions
display LIST
-
starts the http server, launches firefox, waits for events
takes a list of gui objects, and several optional parameters:
debug (0) .. 3 adjust verbosity to stderr silent (0) 1 disables all status messages nolaunch (0) 1 disables launching firefox, connect manually to http://localhost:8888 nochrome (0) 1 chrome mode disables all normal firefox gui elements, setting this option will turn those elements back on. port (8888) first port to try starting the server on, port++ after that delay milliseconds delays each gui update cycle
if
$_[0]
is aWindow
, that window is created, otherwise a default one is added. gui objects from@_
are then added to the window.display
will not return until the the gui quitssee SYNOPSYS and XUL::Gui::Manual for more details
quit
-
shuts down the server (causes a call to
display
to return at the end of the current event cycle) object TAGNAME LIST
-
creates a gui proxy object, allows run time addition of custom tags
object('Label', value=>'hello') is the same as Label( value=>'hello' )
tag NAME
-
returns a CODEREF that generates proxy objects, allows for user defined tag functions
*mylabel = tag 'label'; \&mylabel == \&Label
widget {CODE} HASH
-
group tags together into common patterns, with methods and inheritance
*MyWidget = widget { Hbox( Label( value=> $A{label} ), Button( label=>'OK', attribute 'oncommand' ), @C ) } method => sub{ ... }, method2 => sub{ ... }; $ID{someobject}->appendChild( MyWidget( label=>'widget', oncommand=>\&event_handler ) ); inside widgets, several variables are defined variable contains the passed in %A attributes @C children %M methods $W a reference to the current widget much more detail in XUL::Gui::Manual
extends OBJECT
-
indicate that a widget inherits from another widget or tag
*MySubWidget = widget {extends MyWidget} submethod => sub{...}; more details in XUL::Gui::Manual
attribute NAME
-
includes an attribute name if it exists, only works inside of widgets. NAME is split on whitespace
attribute 'label type' # is syntactic sugar for map {$_ => $A{$_} grep {exists $A{$_}} qw/label type/
XUL STRING
-
converts an XML XUL string to XUL::Gui objects. experimental.
this function is provided to facilitate drag and drop of XML based XUL from tutorials for testing. the perl functional syntax for tags should be used in all other cases
alert STRING
-
open an alert message box
trace LIST
-
carps LIST with object details, and then returns LIST unchanged
function JAVASCRIPT
-
create a javascript function, useful for functions that need to be very fast, such as rollovers
Button( label=>'click me', oncommand=> function q{ this.label = 'ouch'; alert('hello from javascript'); })
gui JAVASCRIPT
-
executes JAVASCRIPT
PRAGMATIC BLOCKS
the following functions all apply pragmas to their CODE blocks. in some cases, they also take a list. this list will be @_
when the CODE block executes. this is useful for sending in values from the gui, if you don't want to use a now {block}
buffered {CODE} LIST
-
delays sending gui updates
buffered { $ID{$_}->value = '' for qw/a bunch of labels/ }; # all labels are cleared at once
cached {CODE}
-
turns on caching of gets from the gui
now {CODE}
-
execute immediately, from inside a buffered or cached block
delay {CODE} LIST
-
delays executing its CODE until the next gui refresh
useful for triggering widget initialization code that needs to run after the gui objects are rendered
noevents {CODE} LIST
-
disable event handling
doevents
-
force a gui update before an event handler finishes
METHODS
# access attributes and properties
$object->value = 5; # sets the value in the gui
print $object->value; # gets the value from the gui
# the attribute is set if it exists, otherwise the property is set
$object->_value = 7; # sets the property directly
# function calls
$object->focus; # void context
$object->appendChild( H2('title') ); # or any arguments are always function calls
in addition to mirroring all of an object's existing javascript methods / attributes / and properties to perl (with identical spelling / capitalization), several default methods have been added to all objects
->removeChildren( LIST )
-
removes the children in LIST, or all children if none given
->removeItems( LIST )
-
removes the items in LIST, or all items if none given
->appendChildren( LIST )
-
appends the children in LIST
->prependChild( CHILD, [INDEX] )
-
inserts CHILD at INDEX (defaults to 0) in the parent's child list
->appendItems( LIST )
-
append a list of items
->replaceItems( LIST )
-
removes all items, then appends LIST
CAVEATS
currently, it is not possible to open more than one window, or to use any features availabled to privileged chrome apps. in most cases you can get away with doing what you need in perl, but having proper file dialogs and drag/drop would be nice, so this is near the top of my todo list.
the code that attempts to find firefox may not work in all cases, patches welcome
AUTHOR
Eric Strom, <ejstrom at gmail.com>
BUGS
please report any bugs or feature requests to bug-xul-gui at rt.cpan.org
, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=XUL-Gui. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
ACKNOWLEDGEMENTS
the mozilla development team
COPYRIGHT & LICENSE
copyright 2009 Eric Strom.
this program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.
see http://dev.perl.org/licenses/ for more information.