NAME
Wx::WidgetMaker - a CGI.pm-like library for wxPerl
SYNOPSIS
use Wx::WidgetMaker;
$q = Wx::WidgetMaker->new(-parent => $frame);
# `print' a control to a pager
$ctrl = $q->h1('H1 text');
$pagesizer = Wx::BoxSizer->new(wxVERTICAL);
$q->print($control, $pagesizer);
# or `print' StaticText
$ctrl1 = $q->print('Password: ');
# or `print' an array ref of controls
$ctrl2 = $q->password_field(
-name => 'password',
-default => 'blue',
-size => 50, # window width, not number of chars
-maxlength => 30,
);
$rowsizer = Wx::BoxSizer->new(wxHORIZONTAL);
$q->print([$ctrl1, $ctrl2], $rowsizer);
$pagesizer->Add($rowsizer);DESCRIPTION
When starting to learn wxPerl, it can be frustrating trying to figure out which widgets handle what functionality. If you've ever done CGI development, you soon realize why it's not a bad idea to leverage the web browser as a graphical user interface: it can be complicated to implement functionality that you take for granted as an HTML/CGI developer.
This module tries to make implementing wxPerl dialogs friendlier to a Perl CGI programmer by using an API similar to CGI.pm. (Specifically, it supports what I consider to be a useful/relevant subset of CGI.pm's :standard export tags.) It tries to adhere as faithfully as reasonable to the CGI API where applicable, and otherwise to try to do something intuitive.
Every form-related method (popup_menu, textfield, etc.) requires a -name parameter. It serves the same purpose as in CGI.pm. The values the user has entered/selected on the form are accessible through $q->param('somename') where 'somename' was given as a -name argument.
METHODS
Here is a reference for the API. Generally methods either take named parameters (-name => 'first') or unnamed parameters passed in the order listed. Optional parameters have their default value listed to the right in parentheses; otherwise, the parameter is required.
new
The constructor.
Parameters
-parent
The parent window (must be a Wx::Window).
Returns
A new Wx::WidgetMaker object.
h1, h2, h3, h4, h5, h6
Analogous to the HTML tags with the same names. These methods display their string parameter in bold font in various sizes, h1 using the largest and h6 the smallest. Note that unlike the HTML tags, there are no linebreaks before or after the text, so you have to explicitly put them on their own row.
Parameters
a text string
Returns
A Wx::StaticText object.
textfield
Parameters
-name
A name for the textfield.
-default, -value ('')
Default text for the textfield.
-size (-1)
The size (width) of the textfield.
-maxlength (unimplemented)
The maximum number of characters that the user can put in the textfield. This is currently unimplemented.
Returns
A Wx::TextCtrl object.
password_field
Parameters
-name
A name for the textfield.
-default, -value ('')
Default text for the textfield.
-size (-1)
The size (width) of the textfield.
-maxlength (unimplemented)
The maximum number of characters that the user can put in the textfield.
Returns
A Wx::TextCtrl object.
textarea
Parameters
-name
A name for the textarea.
-default, -value ('')
Default text for the textarea.
-rows (50)
Height in pixels (XXX: would prefer it to be number of rows of text).
-columns, -cols (100)
Width in pixels (XXX: would prefer it to be the width in chars).
Returns
A Wx::TextCtrl object.
popup_menu
Parameters
-name
A name for the popup_menu.
-value, -values
An reference to a array of values for the menu.
-default, -defaults (first element of -value aref)
The menu value initially selected.
-labels (from -value)
A hash reference associating each value in -values with a text label.
Returns
A Wx::Choice object.
scrolling_list
Parameters
-name
A name for the scrolling_list.
-value, -values
An reference to an array of values for the menu.
-default, -defaults
The menu value initially selected. (first element of -value aref)
-size (50)
The height of the window. (XXX: would prefer it to be the number of items to show at once)
-multiple (false => default style)
True if the user can select multiple menu items.
-labels (from -value)
A hash reference associating each value in -values with a text label.
Returns
A Wx::ListBox object.
checkbox_group
This method is not implemented yet.
Parameters
-name
A name for the checkbox_group.
-value, -values
An reference to an array of values for the underlying checkbox values.
-default, -defaults (no boxes checked)
A value which is initially checked.
-linebreak (false => horizontal)
Set this to a true value in order to display the checkboxes vertically. See the -rows and -cols entries for details.
-labels (from -value)
A hash reference associating each value in -values with a text label.
-rows (1)
If -linebreak is false, the value of -rows is the maximum number of rows to display.
-cols (or -columns) (1)
If -linebreak is true, the value of -cols is the maximum number of cols to display.
-rowheaders
This parameter is not yet implemented.
-colheaders
This parameter is not yet implemented.
-nolabels (false => display labels)
Set this to true to not display any labels (more precisely, to display '' for all labels).
checkbox
Parameters
-name
A required name for the checkbox.
-checked, -selected, -on (false => not checked)
Set any of these optional parameters to a true value in order for the checkbox to be checked initially.
-value
This parameter does nothing. In CGI.pm, you could use it to set a value associated with the checkbox being 'on', but in wxPerl that value is TRUE if the checkbox is checked and FALSE if it is not checked.
-label (-name argument)
An optional label displayed to the user.
Returns
A Wx::CheckBox object.
radio_group
Parameters
-name
A required name for the radio_group.
-value, -values
An reference to an array of values. These values will be displayed as the radio button labels. See also -labels.
-default (none selected)
A value which is initially checked.
-linebreak (false => horizontal)
Set this to a true value in order to display the checkboxes vertically. See the -rows and -cols entries for details.
-labels (use -values)
A synonym for -values. In CGI.pm, -values gives each radio button a value, while -labels gives the labels. For wxPerl, the radio buttons have no associated values, so using either -values or -labels is equivalent. If both are given, -labels takes precedence.
-rows (1)
If -linebreak is false (or not given), the value of -rows is the (maximum) number of rows to display.
-cols (or -columns) (1)
If -linebreak is true, the value of -cols is the (maximum) number of cols to display.
-rowheaders
This parameter is not yet implemented.
-colheaders
This parameter is not yet implemented.
-nolabels (false)
Set this to true to not display any labels.
-caption ('')
This parameter is additional to CGI.pm but is useful here because there is a StaticBox put arround the group of radio buttons (whether you like it or not, Wx::RadioBox does this). Use the -caption option to specify the label for the StaticBox. At some point I might implement the radio_group using individual RadioBoxes and give the option to not surround the radio_group with a StaticBox; this would also allow implementing -rowheaders and -colheaders.
Returns
A Wx::RadioBox object.
submit
Makes a button with text on it. Note that this is not like the submit button in a CGI form because there is no event handler attached to the button, so by default clicking on the button does nothing.
Parameters
-name
A required name for the submit button. Unlike CGI.pm, this name will not be displayed as the button label. It is the window name. Otherwise, this -name parameter would be inconsistent with other methods.
-value, -label ('Submit')
In CGI.pm, -value (or -label) gives the button an associated string "underneath" to pass to the application when the button is pressed. Here, instead, the -value will be the button label. Note that you can retrieve the label string with $button->GetLabel().
Returns
A Wx::Button object.
image_button
Parameters
-name
A required name for the button.
-src
A filename giving the location of the bitmap on the button. You have to give either the absolute filename or the filename relative to the current working directory. Currently, filenames with the folling suffixes are supported (assuming your wxWindows has it compiled in): .bmp, .gif, .xbm, .xpm, .jpg, .jpeg, .png, .pcx, .pnm, .tif, .tiff. Otherwise, it will probably segfault.
-align
This parameter is not implemented.
Returns
A Wx::BitmapButton object.
This isn't a CGI.pm method (though it _is_ an Apache.pm method :), but is handy for either creating a StaticText object or adding control objects to a Sizer.
Parameters
-add
This parameter is overloaded depending on context. If the argument is a plain string, a StaticText object will be returned. If the argument is a Wx::Control object (something returned by one of the other Wx::WidgetMaker methods, like TextCtrl, Choice, etc..) or an array reference of objects, and the -sizer argument is a Wx::Sizer, the control will be added directly to the sizer. See the -sizer parameter description for details.
-sizer (undef)
If the -add argument is a Wx::Control object, the object will be added to the Wx::Sizer specified by the -sizer argument with $sizer->Add($control). If the -add argument is an array reference of Wx::Control objects, all of the objects will be added sequentially to the $sizer.
-option (0)
The `option' parameter to Wx::Sizer::Add.
-flag (0)
The `flag' parameter to Wx::Sizer::Add.
-border (0)
The `border' parameter to Wx::Sizer::Add.
Returns
Either a Wx::StaticText object if -text is a string, or some Wx::Control subclass if -sizer is given.
param
Parameters
either zero or one string
Note that there is no "setter" version of param.
Returns
If no arguments are passed, returns a list of all the child controls' names (assuming they have a name, which they will if they were created with this module). If a name is passed, in list context returns a list of the selected values, while in scalar context returns the first value found.
AUTHOR
Copyright 2002, Scott Lanning <slanning@theworld.com>. All rights reserved.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
SEE ALSO
The wxPerl mailing list.