/ 
TkUtil-Gui-0.01
River stage zero No dependents
/ TkUtil::Gui

NAME

TkUtil::Gui - Easy access to a Perl/Tk GUI state

VERSION

Version 0.01

SYNOPSIS

use TkUtil::Gui;

my $gui = TkUtil::Gui->new(top => $mw);
$gui->Listbox(name => 'List')->pack;
$gui->Button(-text => 'Push Me')->pack;

DESCRIPTION

GUI's can be difficult to set up, but I have found that a lot of code is required to merely get information out of a GUI to pass to another application. This module attempts to rectify this.

It does it's magic by acknowledging that all Tk widget creation switches begin with a "-" and that most widgets have a -text or -textvariable option (or both). In general, this module assigns those for you. And remembers them.

To create widgets, you do it like this:

$frame = $mw->Frame->pack;
$gui = TkUtil::Gui->new(top => $frame);
$widget = $gui->Checkbutton(name => 'utm', -text => 'UTM')->pack;

What magically happens is that $gui assigns a variable reference for you to the Checkbutton, and there are methods to allow you to set it or fetch it.

If your GUI has an "OK" button (or something similar), you can (with a single call) figure out the contents of the entire GUI, returned as a hash.

See eg/Gui.t for an example.

More below.

METHODS

new

$gui = TkUtil::Gui->new(top => $top);

$top is the widget you want to create widgets in. You can change the meaning of $top at any time with the top method. But please, only create one instance of TkUtil::Gui. You can create more, but they don't know about each other, so dumping the state of a GUI won't work like you expect.

AUTOLOAD

This is method that intercepts any undefined entry points. You don't call AUTOLOAD, it is Perl magic that intercepts any non-specified function.

Special options, all of which are optional.

name     [1]
vfrom    [2]
packOpts [3]
onoff    [4]
default  [5]

[1] this is the symbolic name by which this widget is referred. If this is a widget you want to get information out of, then it should be named. Buttons, which generally cause actions to happen, and don't have a lasting state don't need this.

[2] useful for Radiobuttons, where a variable reference is shared. This points to the name of a Radiobutton to share with. See example in eg/Gui.t

[3] this is packing options, as an array reference

[4] useful for Checkbuttons, the test to use to indicate the on and off state. Specified like "on|off" or "true|false" or something similar.

[5] a default value for this widget; only appropriate where a value is meaningful. Currently, not Listboxes, though.

top

$old = $gui->top($top);

Changes parent widget for widget creation. Returns the current definition of "top" before it was changed. This way, you can safely change it in a function, then change it back before you return.

No argument means fetch and return the current value of top.

names

@names = $gui->names();

All of the names maintained by this instance of the class.

vref

$vRef = $gui->vref($widget);

Get the variable reference associated with this widget.

set

$gui->set($name, $value);

Set the named widget to the specified value.

widget

$widget = $gui->widget($name);

Access the widget equated with the specified name.

query_by_name

$result = $gui->query_by_name($name, %opts);

%opts can be:

as_indices - if named widget being queried is Listbox, return
             selected entries as indices vs. selected text

$result will be an array reference for a Listbox. Even if only a single entry is selected in your list.

as_hash

%hash = $gui->as_hash(%opts);

Fetch the entire contents of the GUI as a hash. This is your specified name as the key, and the value is the dereferenced variable reference maintained internally. For a Listbox, the setting would be an array reference to the textual entries from the Listbox (not indices) by default.

%opts can be:

as_indices - return Listbox contents as indices, not text

AUTHOR

X Cramps, <cramps.the at gmail.com>

BUGS

There are undoubtedly widgets I am not dealing with properly here. Let me know what they are, and I'll see about adding code to handle them properly (if possible).

Please report any bugs or feature requests to bug-tkutil-gui at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=TkUtil-Gui. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc TkUtil::Gui

You can also look for information at:

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

Copyright 2009 X Cramps, all rights reserved.

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