NAME
Tk::QuickForm - Quickly set up a form.
SYNOPSIS
require Tk::QuickForm;
my $form= $window->QuickForm(@options
-structure => [
'*page' => 'Page name', #Adds a new page to the notebook. Creates the notebook if needed.
'*section' => 'Section name', #Adds a new section.
some_list => ['radio', 'My values', -values => \@listvalues], #Adds an array of radio buttons.
'*end', #Ends a section.
'*column', #Starts a new column of fields
'*expand', #Expand the next entry in height.
]
)->pack;
$form->createForm;DESCRIPTION
This widget allows you to quickly set up a form for the user to fill out or modify. Attempts are made to make it clear and elegant.
Inherits Tk::Frame. With the -structure option you can define fields the user can modify as well as its layout.
With the put and get methods you can set or retrieve values as a hash.
CONFIG VARIABLES
- Switch: -acceptempty
-
Default value 0. If set the validate method will not trigger on fields containing empty strings.
- Switch: -autovalidate
-
By default 1. Validate the form whenever an entry changes value.
- Switch: -fileimage
-
Set an image object for file items. By default it is the file icon from Tk.
- Switch: -folderimage
-
Set an image object for folder items. By default it is the folder icon from Tk.
- Switch: -fontimage
-
Set an image object for folder items. By default it is the font_icon.png in this package.
- Switch: -postvalidatecall
-
Set this callback if you want to take action on the validation result.
- Switch: -structure
-
You have to set this option. This is the example we use in our testfile:
[ *page' => 'Arrays', '*section' => 'List', -set_list_command => ['list', 'List command test', -values => sub { return @listvalues } ], -set_list_values => ['list', 'List values test', -values => \@listvalues], '*end', '*section' => 'Radio', -set_radio_command => ['radio', 'Radio Command test', -values => sub { return @radiovalues }], -set_radio_values => ['radio', 'Radio values test', -values => \@radiovalues], '*end', '*page' => 'Scalars', '*section' => 'Numbers', -set_boolean => ['boolean', 'Boolean test'], -set_float => ['float', 'Float test'], -set_integer => ['integer', 'Integer test'], '*end', '*section' => 'Scale and Spin', -set_scale => ['scale', 'Scale test'], -set_spin => ['spin', 'Spinbox test'], '*end', '*section' => 'Files', -set_file => ['file', 'File test'], -set_folder => ['folder', 'Folder test'], '*end', '*column', '*section' => 'Colors and fonts', -set_color => ['color', 'Color test'], -set_font => ['font', 'Font test'], '*end', '*section' => 'Free text', -set_text => ['text', 'Text test'], '*end', '*page' => 'User defined', '*section' => 'Scale', -set_scale10 => ['scale10', 'Scale 10 test'], '*end', '*section' => 'Boolean', -set_onoff => ['onoff', 'On/Off 10 test', -offvalue => 'Uit', -onvalue => 'Aan'], '*end', '*section' => 'Text', -set_https => ['https', 'Web link'], '*end', '*page' => 'External', '*section' => 'Single column', -set_ext1 => ['ext1', 'External color test', 'Tk::QuickForm::CColorItem'], '*end', '*expand', '*section' => 'Double column', '*expand', -set_ext2 => ['ext2', 'MyExternal', -height => 8, -width => 40], '*end', ],Only available at create time. See below.
- Switch: -types
-
Add a list of user defined types.
Only available at create time. See below.
THE STRUCTURE OPTION
The -structure option is a list that basically looks like:
[
$switch => $option,
$key => [$type, $label, @options],
...
]SWITCHES
$switch can have the following values:
- *page
-
Creates a NoteBook widget if needed and adds a page with the name in $option.
- *section
-
Creates a new section with the name in $option. You can create nested sections.
- *column
-
Starts a new set of colums at row 0; Does not take a parameter.
- *end
-
Ends current section. Does not take a parameter.
- *expand
-
Verically expands the next item in the list. Does not take a parameter.
TYPES
By default the following types are defined:
- boolean
-
mycheck => ['boolean', 'My check', @options],
Creates a Checkbutton item.
- color
-
mycolor => ['color', 'My color', @options],
Creates an ColorEntry item. See Tk::ColorEntry.
- ext1
-
myexternal => ['ext1', 'My external', 'Full::Class::Name', @options],Adds an external class. See below at USER DEFINED TYPES.
- ext2
-
myexternal => ['ext2', 'Full::Class::Name', @options],Same as ext1 except it occupies all columns. See below at USER DEFINED TYPES.
- file
-
myfile => ['file', 'My file', @options],Creates an Entry item with a button initiating a file dialog.
- float
-
myfloat => ['float', 'My float', @options],Creates an Entry item that validates a floating value.
- folder
-
mydir => ['folder', 'My folder', @options],Creates an Entry item with a button initiating a folder dialog.
- font
-
myfont => ['font', 'My font', @options],Creates an Entry item with a button initiating a font dialog.
- integer
-
myinteger => ['integer', 'My integer', @options],Creates an Entry item that validates an integer value.
- list
-
mylist => ['list', 'My list', -values => \@values], mylist => ['list', 'My list', -values => sub { return @values }],Creates a ListEntry item. See Tk::ListEntry.
- radio
-
myradio => ['radio', 'My radio', -values => \@values], myradio => ['radio', 'My radio', -values => sub { return @values }],Creates a row of radiobuttons.
- scale
-
myscale => ['scale', 'My scale', @options],Creates a Scale item.
- spin
-
myspin => ['spin', 'My spin', @options],Creates a Spinbutton item.
- text
-
mytext => ['text', 'My text', @options],Creates an Entry item.
USER DEFINED TYPES
The -types option lets you add your own item types. Specify as follows:
$window->QuickForm(
-structure => [..],
-types => [
type1 => ['ClassName1', @options1]
type2 => ['ClassName2', @options2]
]
);This may or make not make life easier.
You may prefer to use a class derived from Tk::QuickForm::CBaseClass. However, any class will do as long as:
- It is a valid Tk megawidget
- It accepts a callback option -validatecall,
- It has a put, get, and a validate method.
This also applies to external classes in the ext1 and ext2 types.
METHODS
- createForm
-
Call this method after you created the Tk::QuickForm widget. It will create all the pages, sections and entries.
- get(?$key?)
-
Returns the value of $key. $key is the name of the item in the form. Returns a hash with all values if $key is not specified.
- put(%values)
-
Sets the values in the tabbed form
- validate
-
validates all entries in the form and returns true if all successfull.
LICENSE
Same as Perl.
AUTHOR
Hans Jeuken (hanje at cpan dot org)
BUGS
Unknown. If you find any, please contact the author.
SEE ALSO
- Tk::QuickForm::CBaseClass
- Tk::QuickForm::CBooleanItem
- Tk::QuickForm::CColorItem
- Tk::QuickForm::CFileItem
- Tk::QuickForm::CFloatItem
- Tk::QuickForm::CFolderItem
- Tk::QuickForm::CFontItem
- Tk::QuickForm::CListItem
- Tk::QuickForm::CRadioItem
- Tk::QuickForm::CScaleItem
- Tk::QuickForm::CSpinItem
- Tk::QuickForm::CTextItem