NAME

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

VERSION

Version 1.07

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

Directory

    A Tk::Entry widget with a button that will open a Tk::chooseDirectory window

    CONSTANT: $Tk::FormUI::DIRECTORY

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  => 'My Form',
    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.