NAME

Tk::StyleDialog - Stylish dialog boxes with custom icons.

SYNOPSIS

use Tk::StyleDialog;

my $how_say_you = $mw->StyleDialog (
  -title => 'Uh-oh!',
  -icon  => 'error2',
  -text  => "Now you've done it--you've broken the Internet!\n\n"
          . "What are you going to do now?",

  -buttons        => [ 'Blame the other guy', 'I didn\'t do it',
                       'Plead the 5th', 'Admit guilt' ],
  -button_states  => [ 'normal', 'normal', 'normal', 'disabled' ],
  -default_button => 'Blame the other guy',
  -cancel_button  => 'Plead the 5th',
);

DESCRIPTION

Tk::StyleDialog adds a fun drop-in replacement to the standard Tk dialog boxes. They look like your standard system dialog box, but with customizable icons and buttons. The module comes with a handful of built-in PNG images, from various generations of the standard error, warning, info, and question icons to more familiar icons such as floppy disks, computers, Defragmenter, Control Panel, MSN Butterfly, and Macintosh Apple.

The built-in icon images were obtained from Atom Smasher's Error Message Generator ("SEE ALSO").

OPTIONS

-title

The title of the dialog box. Default is "Error"

-text

The text of the dialog message. Default is "An error has occurred."

-icon

Name of a built-in icon or an already existing Tk::Photo object.

-buttons

Array of button labels.

-default_button

The default button has a darker border around it, and is automatically selected if the user hits the Return key. By default, the default button is the first button in your list. Specify the label of the default button here to override that.

-cancel_button

The cancel button is the default button that is returned if the user hits the Escape key, or closes the dialog via the window manager's "Close" button. The default cancel button is the very last button in your list, or set the cancel button to match the label of another button to override that.

-button_states

This is an array of the states for your buttons. The order of this array has to line up with the order of -buttons. Each element should be either normal or disabled. An undef value is assumed to be normal.

-standalone

By default, the dialog window will be treated as a transient window to the window that called it. Until the dialog is cleared, input to its parent window isn't allowed. This is suitable for most cases, but if you want the dialog to be its own standalone Toplevel, set -standalone to be 1.

-center

Center the window in the middle of your screen. By default, -center is 1, because a dialog box appearing in the middle of the screen seems to be standard among all programs that summon dialog boxes. It gets a little tricky with dual monitors, though, because Tk::screenwidth and Tk::screenheight will report the combined dimensions of all monitors. This behavior was noted on Linux with an NVIDIA graphics card and might not be true of all dual monitor setups.

If you'd prefer that your dialog doesn't center itself on the screen, set -center to be 0.

-grab

Set -grab to equal global for the dialog window to have a global grab over the user's entire desktop, preventing all input to their desktop until the dialog box has been answered. Note that system events won't be blocked by the global grab, such as the three finger salute to Microsoft or the X Server events. The default behavior is to only grab control away from the parent program.

BUILT-IN ICONS

Four generic icons are built into the module: attention, error, info, and question. The icons are base64-encoded in Tk::StyleDialog. Additional icons from Atom Smasher's collection are loaded only when one of them is called for the first time.

The module Tk::StyleDialog::Builtins contains the base64 data for every icon in Atom Smasher's set, whereas Tk::StyleDialog alone only contains the four generic icons. Tk::StyleDialog::Builtins will be dynamically loaded if you reference a built-in icon outside of the default four.

You can create your own built-in icons in a sub-class by modifying the data structure at $Tk::StyleDialog::BUILTIN_ICONS, for example:

$Tk::StyleDialog::BUILTIN_ICONS->{"attention"} = $base64_data;

This is a full breakdown of the built-in icons, including the four default icons and the entire collection from Tk::StyleDialog::Builtins.

aim_guy         - Blue AIM guy icon
aol_icon        - Blue AOL icon
attention       - Yellow triangle around an exclamation mark
bomb            - Round black bomb icon
bomb_dynamite   - Icon of a bundle of dynamite and a trigger
bomb_grenade    - Icon of a grenade
bulb            - White light bulb
butterfly       - MSN Butterfly icon
cake            - Slice of pink cake on a blue plate
circularsaw     - Icon of a handheld circular saw
control_panel   - Generic control panel icon
cow             - Icon of a cow and a computer tower
defrag          - Disk Defragmenter icon
disk_blue       - Generic blue floppy disk icon
disk_blue_label - Blue floppy disk with a label
disk_orange     - Generic orange floppy disk
disk_red        - Generic red floppy disk
disk_red_label  - Red floppy disk with a label
disk_skull      - Gray floppy disk with skull and crossbones emblem on it
disk_yellow     - Generic yellow floppy disk
error           - Old-school X in a red circle error dialog icon (like Win 95)
error2          - Modern, shiny incarnation of an error dialog icon
error3          - Beveled error dialog icon (like Windows XP)
error4          - A red X icon
file_cabinet    - File cabinet icon
find            - Find Files icon
floppy_drive    - Generic floppy drive icon
fortunecookie   - Icon of a fortune cookie
garbage_empty   - Empty garbage can
garbage_full    - Bloated garabage can
gun             - Icon of a revolver pistol
hammer          - Icon of a hammer
heart           - Icon of a shiny red heart
help            - Old-school Windows Help icon
hub             - Icon of a hardware hub of sorts (networking?)
hwinfo          - Icon of a PCI device with blue "i" bubble above it
ie5             - Icon of old-school Internet Explorer
info            - Speech bubble with an "i" inside
keys            - Generic icon of keys
keys2           - Old Windows key icon
keys3           - Generic key and padlock icon
labtec          - Icon of a server or something?
mac             - Striped colorful Apple logo
mail            - Generic icon of an envelope
mail_deleted    - Same envelope with a red X emblem in the corner.
mailbox         - Mailbox with the flag down
mouth           - Smiling mouth icon
msdos           - MS-DOS icon
mycomputer      - A "My Computer" icon
mycomputer2     - A "My Computer" icon
mycomputer3     - A "My Computer" icon
newspaper       - Generic newspaper icon
peripheral      - Generic computer peripheral icon
plant_leaf      - A certain green leafy plant
pocketknife     - A swiss army pocket knife
question        - Icon of a speech bubble with a "?" inside
radiation       - Yellow and black radiation symbol
ram             - Icon of a couple sticks of RAM
recycle         - Green recycle arrows logo
recycle2        - Recycle arrows enveloping a globe of Earth
scanner         - Generic scanner icon
screw           - Golden screw icon
screw2          - Gray screw icon
setup           - Generic icon for "setup.exe" type programs
skull           - Black skull and crossbones
skull2          - Picture of a skull
skull3          - White skull and crossbones
tux             - Icon of our favorite Linux mascot
tux_config      - Tux dressed up like a repairman
ups             - Icon of an uninterruptible power supply
zipdisk         - Icon of a single zip disk
zipdisks        - Icon of numerous zipdisks

METHODS

StyleDialog doesn't have any methods. Creating a new StyleDialog automatically calls the Show() method, which takes the same arguments as the constructor. In other words, don't worry about it.

ADVERTISED WIDGETS

No advertised widgets. The constructor and Show() should grab control of your program until the dialog is dismissed.

BUGS

To be discovered.

If anyone has any objection to the use of trademarked icons used in the built-in collection, they'll have to be removed. To that end I'd probably recommend that if the use of a particular icon is absolutely crucial to your program that you include it with your program and pass in a Tk::Photo object instead.

CHANGES

0.03  Sep 19 2008
- Fixed a bug with "-grab => global" not working properly.

0.02  Sep 19 2008
- Added a binding so that the space bar invokes the default button in addition
  to just the return key.
- Added an option of `-center => 0` to stop the default behavior of centering
  the dialog box on-screen.
- Fixed the Makefile so it doesn't require Perl 5.10 :)

0.01  Sep 18 2008
- Initial release.

SEE ALSO

Atom Smasher's Error Message Generator, from which all the builtin icons were obtained. http://atom.smasher.org/error/

AUTHOR

Casey Kirsle, http://www.cuvou.com/

This code is distributed under the same terms as Perl itself. The icon set was downloaded from Atom Smasher's Error Message Generator, so see the author there for additional information about the icons.