/ 
Tk-FormUI-1.05
River stage zero No dependents
/ Tk::FormUI

NAME

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

VERSION

Version 1.05

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.