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.

FILE DIALOG VARIABLES

A number of config variables are forwarded to the file dialog widget used in this module. Look in Tk::FilePicker and Tk::FileBrowser for their meaning. They are:

-diriconcall

-fileiconcall

-linkiconcall

-msgimage

-newfolderimage

-reloadimage

-warnimage

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 as label on a Tk::LabFrame. You can create nested sections.

*frame

Similar to *section just does not take a name parameter. Useful for dividing the space.

*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

cpanm Tk::QuickForm

perl -MCPAN -e shell
install Tk::QuickForm