NAME

Tk::AppWindow - an application framework based on Tk

SYNOPSIS

 my $app = new Tk::AppWindow(@options,
    -extensions => ['ConfigFolder'],
 );
 $app->MainLoop;

DESCRIPTION

An extendable application framework written in perl/Tk. The aim is maximum user configurability and ease of application building.

To get started read Tk::AppWindow::OverView.

This document is a reference manual.

CONFIG VARIABLES

Switch: -appname

Set the name of your application.

If this option is not specified, the name of your application will be set to the filename of your executable with the first character in upper case.

Switch: -commands

Defines commands to be used in your application. It takes a paired list of command names and callbacks as parameter.

 my $app = $k::AppWindw->new(
    -commands => [
       do_something1 => ['method', $obj],
       do_something2 => sub { return 1 },
    ],
 );

Only available at create time.

Name : errorColor

Class : ErrorColor

Switch: -errorcolor

Default value '#FF0000' (red).

Switch: -extensions

Specifies the list of extensions to be loaded.

 my $app = $k::AppWindw->new(
    -extensions => [ 
       qw/Art Balloon ConfigFolder
       Help Keyboard MDI MenuBar
       Navigator Panels Plugins
       SDI Settings StatusBar ToolBar/
    ],
 );

The following order matters for the buildup of menus and bars. Only available at create time.

Switch: -logo

Specifies the image file to be used as logo for your application. Default value is Tk::findINC('Tk/AppWindow/aw_logo.png').

Switch: -namespace

Specifies an additional name space for extensions and plugins. If you set it, for example, to 'Foo::Bar', then your extensions may also live in 'Foo::Bar::Ext' and your plugins may live in 'Foo::Bar::Plugins'.

Only available at create time.

Switch: -verbose

Default value is 0. Set or get verbosity. Does not do anything at this moment. Meant for logging.

COMMANDS

quit

Calls the CmdQuit method. See there.

METHODS

addPostConfig('Method', $obj, @options)

Only to be called by extensions at create time. Specifies a callback te be executed after main loop starts.

Callbacks are executed in the order they are added.

addPreConfig(@configs)

Only to be called by extensions at create time. Specifies configs to the ConfigSpec method executed in Populate.

appName($name)

Sets and returns the application name. Same as $app->configPut(-name => $name), or $app->configGet($name).

BalloonAttach@options

Calls the Attach method of the Balloon widget if the extens Balloon is loaded

CanQuit

Returns 1. It is called when Tk::AppWindow tests all extensions if they can quit. You can overwrite it when you inherit Tk::AppWindow.

cmdConfig(@commands)

 $app->cmdConfig(
    command1 => ['SomeMethod', $obj, @options],
    command2 => [sub { do whatever }, @options],
 );

cmdConfig takes a paired list of commandnames and callback descriptions. It registers them to the commands table. After that cmdExecute can be called on them.

cmdExecute('command_name', @options);

Looks for the callback assigned to command_name and executes it. returns the result.

cmdExists('command_name')

Checks if command_name can be used as a command. Returns a boolean.

cmdHookAfter('command_name', @callback)

Adds a hook to after stack of the callback associated with 'command_name'. See Tk::AppWindow::BaseClasses::Callback.

cmdHookBefore('command_name', @callback)

Adds a hook to before stack of the callback associated with 'command_name'. See Tk::AppWindow::BaseClasses::Callback.

cmdRemove('command_name')

Removes 'command_name' from the command stack.

cmdUnhookAfter('command_name', @callback)

unhooks a hook from after stack of the callback associated with 'command_name'. See Tk::AppWindow::BaseClasses::Callback.

cmdUnhookBefore('command_name', @callback)

unhooks a hook from before stack of the callback associated with 'command_name'. see Tk::AppWindow::BaseClasses::Callback.

configGet('-option')

Equivalent to $app-cget. Except here you can also specify the options added by configInit

configHookAfter('-configvariable', @callback)

Adds a hook to the after stack of the callback associated with a config variable'. See Tk::AppWindow::BaseClasses::Callback. Only works on config variables created through configInit

configHookAfter('-configvariable', @callback)

Adds a hook to teh before stack of the callback associated with a config variable'. See Tk::AppWindow::BaseClasses::Callback. Only works on config variables created through configInit

configInit(@options)

 $app->configInit(
    -option1 => ['method', $obj, @options],
    -option2 => [sub { do something }, @options],
 );

Add options to the options table. Usually called at create time. But worth experimenting with.

configMode

Returns 1 if MainLoop is not yet running.

configPut(-option = $value)>

Equivalent to $app-configure. Except here you can also specify the options added by configInit

configUnhookAfter('-configvariable', @callback)

Removes a hook from the after stack of the callback associated with a config variable'. See Tk::AppWindow::BaseClasses::Callback. Only works on config variables created through configInit

configUnhookBefore('-configvariable', @callback)

Removes a hook from the after stack of the callback associated with a config variable'. See Tk::AppWindow::BaseClasses::Callback. Only works on config variables created through configInit

CreateCallback('MethodName', $owner, @options);

CreateCallback(sub { do whatever }, @options);

Creates and returns a Tk::AppWindow::Baseclasses::Callback object. A convenience method that saves you some typing.

extExists($name)

Returns 1 if $name is loaded.

extGet('Name')

Returns reference to extension object 'Name'. Returns undef if 'Name' is not loaded.

extList

Returns a list of all loaded extensions

extLoad('Name');

Loads and initializes an extension. Terminates application if it fails.

Called at create time.

fileSeparator

Returns the correct file separator for your operating system. '\' for windows and '/' for all the others.

getArt($icon, $size)

Checks if extension Art is loaded and returns requested image if so. If $size is not specified, default size is used.

MenuItems

Returns a list of two items used by the MenuBar extension. The first defines the application menu. The second is the menu option Quit in this menu. Overwrite this method to make it return a different list. See also Tk::AppWindow::Ext::MenuBar

OSName

Returns the name of the operating system you are running.

popDialog($title, $message, $icon, @buttons)

Pops up a dialogbox with @buttons. The first button is the default button. Returns the name of the button pressed. If you press the Escape key it wil return '*Cancel*'.

popEntry($title, $message, $value, $icon)

Pops up a dialog box with an Entry widget. returns the entered value if the ok button is pressed. Otherwise returns undef..

popMessage($message, $icon, ?$size?)

Pops up a message box with a close button.

StatusMessage($text)>

Sends a message to the status bar if it is loaded. See Tk::AppWindow::Ext::StatusBar

progressAdd($name, $label, $size, $variable)

Adds a progress bar to the status bar. Extension StatusBar must be loaded for this to work.

progressRemove($name)

Remves a progress bar from the status bar. Extension StatusBar must be loaded for this to work.

ToolItems

Returns an empty list. It is called by the ToolBar extension. Overwrite it if you like.

Verbose

Set or get verbosity. Same as $app->configPut(-verbose => $value) or $self->configGet('-verbose');

AUTHOR

Hans Jeuken (hanje at cpan dot org)

LICENSE

Same as Perl.

BUGS

Unknown. Probably plenty. If you find any, please contact the author.

SEE ALSO

Tk::AppWindow::OverView

Tk::AppWindow::BaseClasses::Extension