NAME

Tk::FormUI - A Moo based object oriented interface for creating forms for use with Tk

VERSION

Version 1.1

SYNOPSIS

use Tk::FormUI;

my $form = Tk::FormUI->new;

## Add an Entry field for text
$form->add_field(
  key     => 'user_name',
  label   => 'User name',
  type    => $Tk::FormUI::ENTRY,
  width   => 40,
  default => 'John Doe',
);

## Add a Radio Button field
$form->add_field(
  key   => 'gender',
  label => 'Gender',
  type  => $Tk::FormUI::RADIOBUTTON,
  choices => [
    {
      label => 'Male',
      value => 'male',
    },
    {
      label => 'Female',
      value => 'female',
    },
  ],
);

## Display the form and capture the data returned
my $data = $form->show;

TYPES

The Tk::FormUI recognizes the following values for the "type" key when adding or defing a field.

'Entry'

A Tk::Entry widget
CONSTANT: $Tk::FormUI::ENTRY

'Checkbox'

A group of Tk::CheckButton widgets that correspond to the choices
CONSTANT: $Tk::FormUI::CHECKBOX

'RadioButton'

A group of Tk::RadioButton widgets that correspond to the choices
CONSTANT: $Tk::FormUI::RADIOBUTTON

'Combobox'

A Tk::BrowserEntry widget with a drop-down list that correspond to the choices
CONSTANT: $Tk::FormUI::COMBOBOX

ATTRIBUTES

title

Title of the form
DEFAULT: 'Form'

message

Message to display at the top of the form.
DEFAULT: ''

message_font

Font to use for the form's message
DEFAULT: 'times 12 bold'

fields

The fields contained in this form

button_label

The text to appear on the button at the bottom of the form.
You may place the ampersand before the character you want to use as
a "hot key" indicating holding the Alt key and the specified character
will do the same thing as pressing the button.
DEAULT: '&OK'

button_font

Font to use for the form's button
DEFAULT: 'times 10'

min_width

Minimum width of the form window
DEFAULT: 300

min_height

Minimum height of the form window
DEFAULT: 80

submit_on_enter

Boolean value indicating if pressing the Enter key should simulate clicking
the button to submit the form.
DEFAULT: 1

cancel_on_escape

Boolean value indicating if pressing the Escape key should simulate closing
the window and canceling the form.
DEFAULT: 1

error_font

Font to use for the form's error messages
DEFAULT: 'times 12 bold'

error_marker

String used to indicate an error
DEFAULT: '!'

error_font_color

Font color to use when displaying error message and error marker
DEFAULT: 'red'

METHODS

add_field(...)

Description

Add a field to the form

Parameters

A list of key / value pairs should be provide

type     - Type of field
key      - Key to use in hash returned by the show() method
label    - Text to display next to the field
readonly - Boolean indicating if field is read only and cannot be
           modified
choices  - ARRAY reference containing hashes that define the possible
           values for the field.
           REQUIRED for Checkbox, RadioButton, and Combobox
           Each hash must have the following key/value pairs
            label - String to be displayed
            value - Value to return if selected

Return

UNDEF on error, or the field object created

show($parent)

Description

Show the form as a child of the given parent, or as a new MainWindow if a parent is not specified; The function will return if the users cancels the form or submits a form with no errors.

Parameters

$parent - Parent window, if none is specified, a new MainWindow will be created

Return

UNDEF when canceled, or a HASH reference containing whose keys correspond to the key attributes of the form's fields

show_once($parent)

Description

Show the form as a child of the given parent, or as a new MainWindow if a parent is not specified. Once the user submits or cancels the form, the function will return.

Parameters

$parent - Parent window, if none is specified, a new MainWindow will be created

Return

UNDEF when canceled, or a HASH reference containing whose keys correspond to the key attributes of the form's fields

initialize($param)

Description

initialize the form from a HASH reference, JSON string, or JSON file. In all cases, the hash should have the following format

{
  title
  fields => [
    {
      type  => 'Entry',
      key   => 'name',
      label => 'Name',
    },
    {
      type  => 'Radiobutton',
      key   => 'sex',
      label => 'Gender',
      choices => [
        {
          label => 'Male',
          value => 'male',
        },
        {
          label => 'Female',
          value => 'female',
        },
      ],
    }
  ]

Parameters

$param - HASH reference, or scalar containin JSON string, or filename

Return

NONE

set_field_data($hash)

Description

Use the key/values of the provided hash to set the corresponding field values

Parameters

$hash - Hash reference containing key /values whose keys correspnd to the various field keys

Return

NONE

clear_errors()

Description

Clear errors on all form fields

Parameters

NONE

Return

NONE

field_by_key($key)

Description

Return the field associated with the provided key or UNDEF if not found.

Parameters

$key - The key associated with the desired field

Return

UNDEF if not found, or a Tk::FormUI field object

error_by_key($key, $error)

Description

Set the error for the field associated with the given key

Parameters

$key - The key associated with the desired field $error - Error message for the given field

Return

NONE

has_errors()

Description

Returns TRUE if any field in the form has an error

Parameters

NONE

Return

TRUE if any field has an error

AUTHOR

Paul Durden <alabamapaul AT gmail.com>

COPYRIGHT & LICENSE

Copyright (C) 2015 by Paul Durden.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Tk::FormUI

perl -MCPAN -e shell
install Tk::FormUI