/ 
Tk-AppWindow-0.18
River stage one • 1 direct dependent • 1 total dependent
/ Tk::AppWindow

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 and Tk::AppWindow::CookBook.

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 = Tk::AppWindow->new(
   -extensions => [ 
      qw/Art ConfigFolder Daemons 
      Help Keyboard MDI MenuBar
      Panels Plugins SDI Selector
      Settings SideBars StatusBar
      ToolBar/
   ],
);

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

Name : linkColor
Class : LinkColor
Switch: -linkcolor

Foreground color for links. Default value '#3030DF'.

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: -savegeometry

Default value 0. Saves the geometry on quit and loads it on start. Only works if the extension ConfigFolder is loaded.

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).

balloon

Returns a reference to the Balloon widget.

BalloonAttach$widget, $text

Attaches a balloon message to $widget.

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, $default],
   -option2 => [sub { do something }, @options, $default],
);

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

Always specify $default. The last thing you specify is always the default value. set it undef if you want it to be ignored.

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

configRemove('-option')

Removes '-option from the config hash. Usefull when unloading a plugin that configures an option with 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.

log($message)

Log $message

logDisabled(?$flag?)

Disable/enable logging of messages.

logError($message)

Log $message as an error

logWarning($message)

Log $message as a warning

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

openURL($file_or_web)

Opens $file_or_web in the default application of your desktop.

Please provide 'https://' or whatever protocol in front if it is on the web.

pause($time)

Pauses the app for $time miliseconds in a non blocking way.

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..

popForm(%options)

This method uses Tk::QuickForm to pop up a form for the user to fill out. Returns a hash with all defined keys if the user clicks the Ok button, Returns an empty hash if the user clicks cancel. It can take the following options:

-acceptempty

Boolean. By default false. If set, empty fields will not evaluate as error.

-initialvalues

A reference to a hash with default values to be loaded.

-oktext

By default 'Ok'. You can change it to any text you like.

-structure

Same option as in Tk::QuickForm. See there.

-title

The window title.

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

Pops up a message box with a close button.

StatusAttach$widget, $text

Attaches a status message to $widget

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)

Removes 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.

FILE DIALOGS

The pickWhatEver methods launch filedialogs. They are meant as a replacement of the classic getOpenFile and getSaveFile methods. The pick methods can be called with a lot of the options for Tk::FilePicker and Tk::FileBrowser. See also there. Additionaly, they can also be called with these options:

-initialdir

Directory to load on pop.

-initialfile

Suggested file name.

The pick methods always return their results in list context. So even when you expect only one result you have to do:

my ($file) = $fp->pickWhatEver(%options);
pick

The basic pick method.

pickFileOpen

Calls pick configured to select one file for opening. Equivalent to:

my ($file) = $window->pick(
   -checkoverwrite => 0,
   -showfolders => 1,
   -showfiles => 1,
   -selectmode => 'single',
   -selectstring => 'Open',
   -title => 'Open file',
);
pickFileOpenMulti

Calls pick configured to select multiple files for opening. Equivalent to:

my @files = $window->pick(
   -checkoverwrite => 0,
   -showfolders => 1,
   -showfiles => 1,
   -selectmode => 'extended',
   -selectstring => 'Open',
   -title => 'Open file',
);
pickFileSave

Calls pick configured to select one file for saving. Pops a dialog for overwrite if the selected file exists. Equivalent to:

my ($file) = $window->pick(
   -checkoverwrite => 1,
   -showfolders => 1,
   -showfiles => 1,
   -selectmode => 'single',
   -selectstring => 'Save',
   -title => 'Save file',
);
pickFolderSelect

Calls pick configured to select one folder. Equivalent to:

my ($folder) = $window->pick(
   -checkoverwrite => 0,
   -showfolders => 1,
   -showfiles => 0,
   -selectmode => 'single',
   -selectstring => 'Select',
   -title => 'Select folder',
);

AUTHOR

Hans Jeuken (hanje at cpan dot org)

LICENSE

Same as Perl.

BUGS

If you find any, please contact the author.

SEE ALSO

Tk::AppWindow::OverView
Tk::AppWindow::CookBook
Tk::AppWindow::BaseClasses::Extension