The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Tk-StyleDialog-0.04
River stage zero No dependents
++
/ Tk::StyleDialog

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.04  Sep 24 2008
  - Fixed Makefile.PL to name Tk and Tk::PNG as dependencies (to stop being
    nagged by CPAN test failures :P)

  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.