NAME

       Tk::FontDialog - a font dialog widget for perl/Tk

SYNOPSIS

           use Tk::FontDialog;
           $font = $top->FontDialog->Show;

DESCRIPTION

       Tk::FontDialog implements a font dialog widget.

       The dialog is displayed by calling the Show method. The returned value is either the
       selected font (if the dialog was closed with the Ok button) or undef (otherwise). The
       exact type of the return value is either a Tk::Font object (in Tk800) or a font name
       string (usually something like "font1"). Both can be used as values in Tk "-font" options.
       See "GetDescriptiveFontName"

       In the Family and Size listboxes, the font family and font size can be specified. The
       checkbuttons on the right turn on bold, italic, underlined and overstriked variants of the
       chosen font. A sample of the font is shown in the middle area.

       With the "Alt sample" checkbutton, it is possible to show all characters in the charset
       instead of the default text. "Fixed only" restricts the font family list to fixed fonts
       only. If the "Nicefonts" checkbutton is set, then the font names in the listbox are
       displayed in the corresponding font. Note that this option can be slow if a lot of fonts
       are installed or for 16 bit fonts.

       A click with the right button in the font size listbox pops up a window to enter arbitrary
       font sizes.

WIDGET-SPECIFIC OPTIONS

       -font
           The dialog font.

       -initfont
           The initial font.

       -fontsizes
           A list of font sizes. The default contains sizes from 0 to 72 points (XXX or pixels?).

       -nicefont
           If set, font names are displayed in its font style. This may be slow, especially if
           you have many fonts or 16 bit fonts (e.g. Asian fonts).

       -nicefontsbutton
           If set to false, then the "Nice fonts" button is not displayed.

       -fixedfont
           If set, proportional font families are not listed, leaving only the fixed fonts. This
           is slow, as each font must be checked to see if it is fixed or proportional.

       -fixedfontsbutton
           If set to false, then the "Fixed fonts" button is not displayed.

       -sampletext
           The sample text which should contain all letters. The default is "The Quick Brown Fox
           Jumps Over The Lazy Dog" German readers may probably use "Franz jagt im komplett
           verwahrlosten Taxi quer durch Bayern".

INTERNATIONALIZATION

       There are a couple of options to change the labels of the dialog. Note that you can
       prepend a tilde ("~") to get an accelerator key with "Alt". Here is a list of these
       options with the default (English) setting:

       -familylabel (Family:)
       -sizelabel (Size:)
       -weightlabel (Bold)
       -slantlabel (Italic)
       -underlinelabel (Underline)
       -overstrikelabel (Overstrike)
       -oklabel (OK)
       -applylabel (Apply)
       -cancellabel (Cancel)
       -altsamplelabel (Alt sample)
       -nicefontslabel (Nicefonts)
       -fixedfontslabel (Fixed Only)
       -title (Choose font)
       -customsizetitle (Choose font size)

METHODS IN Tk::Widget

       RefontTree(-font => $font)
           Additionally, the convenience method RefontTree is defined in the Tk::Widget
           namespace. Using this method a font definition could be applied to a complete subtree
           of a widget. This is similar to the method RecolorTree. Calling RefontTree looks like
           this:

               $font = $mw->FontDialog->Show;
               $mainwindow->RefontTree(-font => $font) if defined $font;

           By default RefontTree does not change the font of canvas elements.  This can be done
           by specifying "-canvas => 1".

       GetDescriptiveFontName($fontname)
           Return a "descriptive" font name (just like form [3] as described in Tk::Font). The
           return value from the Show() method has the disadvantage that it is only valid for the
           current Tk session. A "descriptive" font name may be stored and reused later.

CAVEAT

       Note that font names with whitespace like "New century schoolbook" or "MS Sans Serif" can
       cause problems when using in a -font option. The solution is to put the names in Tcl-like
       braces, like

           -font => "{New century schoolbook} 10"

EXAMPLES

       To apply a selected font to a specific widget, use the following snippet:

           $font = $mw->FontDialog->Show;
           if (defined $font) {
               $button->configure(-font => $font);
           }

       This example uses the convenience method RefontTree to apply the new font to the whole
       application:

           use Tk;
           use Tk::FontDialog;
           $mw = tkinit;
           $mw->Label(-text => "Test")->pack;
           $mw->Button(-text => "Another test")->pack;
           $mw->Button(-text => "Use Tk::FontDialog",
                       -command => sub {
                           my $font = $mw->FontDialog->Show;
                           if (defined $font) {
                               $mw->RefontTree(-font => $font);
                           }
                       })->pack;
           MainLoop;

       To get the "descriptive" font name:

           $font = $mw->FontDialog->Show;
           if (defined $font) {
               $font_descriptive = $mw->GetDescriptiveFontName($font);
               print $font_descriptive, "\n";
           }

AVAILABILITY

       The latest released version is available from cpan (e.g.
       <http://search.cpan.org/~srezic/>). The latest development version is available from
       github (<http://github.com/eserte/tk-fontdialog>).

BUGS/TODO

         - ConfigSpecs handling is poor
           put at least -font into configspecs
         - run test, call dialog for 2nd time: immediate change of font?
         - better name for nicefont
         - restrict on charsets and encodings (xlsfonts? X11::Protocol::ListFonts?)
           difficult because core Tk font handling ignores charsets and encodings

SEE ALSO

       Tk::Font

AUTHOR

       Slaven Rezic <slaven@rezic.de>

       Suggestions by Michael Houghton, Martin Thurn, Jack, Justin Kozlowitz and others.

COPYRIGHT

       Copyright (c) 1998,1999,2003,2004,2005,2010 Slaven Rezic. All rights reserved.  This
       module is free software; you can redistribute it and/or modify it under the same terms as
       Perl itself.