util/src/TclTk/tk8.6.12/doc/fontchooser.n

   1 '\"
   2 '\" Copyright (c) 2008 Daniel A. Steffen <das@users.sourceforge.net>
   3 '\"
   4 '\" See the file "license.terms" for information on usage and redistribution
   5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   6 '\"
   7 .TH fontchooser n "" Tk "Tk Built-In Commands"
   8 .so man.macros
   9 .BS
  10 '\" Note:  do not modify the .SH NAME line immediately below!
  11 .SH NAME
  12 fontchooser \- control font selection dialog
  13 .SH SYNOPSIS
  14 \fBtk fontchooser\fR \fBconfigure\fR ?\fI\-option value \-option value ...\fR?
  15 .sp
  16 \fBtk fontchooser\fR \fBshow\fR
  17 .sp
  18 \fBtk fontchooser\fR \fBhide\fR
  19 .BE
  20 .SH DESCRIPTION
  21 .PP
  22 The \fBtk fontchooser\fR command controls the Tk font selection dialog. It uses
  23 the native platform font selection dialog where available, or a dialog
  24 implemented in Tcl otherwise.
  25 .PP
  26 Unlike most of the other Tk dialog commands, \fBtk fontchooser\fR does not
  27 return an immediate result, as on some platforms (Mac OS X) the standard font
  28 dialog is modeless while on others (Windows) it is modal. To accommodate this
  29 difference, all user interaction with the dialog will be communicated to the
  30 caller via callbacks or virtual events.
  31 .PP
  32 The \fBtk fontchooser\fR command can have one of the following forms:
  33 .TP
  34 \fBtk fontchooser\fR \fBconfigure \fR?\fI\-option value \-option value ...\fR?
  35 .
  36 Set or query one or more of the configurations options below (analogous to Tk
  37 widget configuration).
  38 .TP
  39 \fBtk fontchooser\fR \fBshow\fR
  40 .
  41 Show the font selection dialog. Depending on the platform, may return
  42 immediately or only once the dialog has been withdrawn.
  43 .TP
  44 \fBtk fontchooser\fR \fBhide\fR
  45 .
  46 Hide the font selection dialog if it is visible and cause any pending
  47 \fBtk fontchooser\fR \fBshow\fR command to return.
  48 .PP
  49 .SH "CONFIGURATION OPTIONS"
  50 .TP
  51 \fB\-parent\fR
  52 Specifies/returns the logical parent window of the font selection dialog
  53 (similar to the \fB\-parent\fR option to other dialogs). The font selection
  54 dialog is hidden if it is visible when the parent window is destroyed.
  55 .TP
  56 \fB\-title\fR
  57 Specifies/returns the title of the dialog. Has no effect on platforms where the
  58 font selection dialog does not support titles.
  59 .TP
  60 \fB\-font\fR
  61 Specifies/returns the font that is currently selected in the dialog if it is
  62 visible, or that will be initially selected when the dialog is shown (if
  63 supported by the platform). Can be set to the empty string to indicate that no
  64 font should be selected. Fonts can be specified in any form given by the "FONT
  65 DESCRIPTION" section in the \fBfont\fR manual page.
  66 .TP
  67 \fB\-command\fR
  68 Specifies/returns the command prefix to be called when a font selection has
  69 been made by the user. The command prefix is evaluated at the global level
  70 after having the specification of the selected font appended. On platforms
  71 where the font selection dialog offers the user control of further font
  72 attributes (such as color), additional key/value pairs may be appended before
  73 evaluation. Can be set to the empty string to indicate that no callback should
  74 be invoked. Fonts are specified by a list of form [3] of the "FONT DESCRIPTION"
  75 section in the \fBfont\fR manual page (i.e. a list of the form
  76 \fI{family size style ?style ...?}\fR).
  77 .TP
  78 \fB\-visible\fR
  79 Read-only option that returns a boolean indicating whether the font selection
  80 dialog is currently visible. Attempting to set this option results in an error.
  81
  82 .PP
  83 .SH "VIRTUAL EVENTS"
  84 .TP
  85 \fB<<TkFontchooserVisibility>>\fR
  86 Sent to the dialog parent whenever the visibility of the font selection dialog
  87 changes, both as a result of user action (e.g. disposing of the dialog via
  88 OK/Cancel button or close box) and of the \fBtk fontchooser\fR
  89 \fBshow\fR/\fBhide\fR commands being called. Binding scripts can determine the
  90 current visibility of the dialog by querying the \fB\-visible\fR configuration
  91 option.
  92 .TP
  93 \fB<<TkFontchooserFontChanged>>\fR
  94 Sent to the dialog parent whenever the font selection dialog is visible and the
  95 selected font changes, both as a result of user action and of the \fB\-font\fR
  96 configuration option being set. Binding scripts can determine the currently
  97 selected font by querying the \fB\-font\fR configuration option.
  98 .PP
  99 .SH NOTES
 100 .PP
 101 Callers should not expect a result from \fBtk fontchooser\fR \fBshow\fR and may
 102 not assume that the dialog has been withdrawn or closed when the command
 103 returns. All user interaction with the dialog is communicated to the caller via
 104 the \fB\-command\fR callback and the \fB<<TkFontchooser*>>\fR virtual events.
 105 It is implementation dependent which exact user actions result in the callback
 106 being called resp. the virtual events being sent. Where an Apply or OK button
 107 is present in the dialog, that button will trigger the \fB\-command\fR callback
 108 and \fB<<TkFontchooserFontChanged>>\fR virtual event. On some implementations
 109 other user actions may also have that effect; on Mac OS X for instance, the
 110 standard font selection dialog immediately reflects all user choices to the
 111 caller.
 112 .PP
 113 In the presence of multiple widgets intended to be influenced by the font
 114 selection dialog, care needs to be taken to correctly handle focus changes: the
 115 font selected in the dialog should always match the current font of the widget
 116 with the focus, and the \fB\-command\fR callback should only act on the widget
 117 with the focus. The recommended practice is to set font dialog \fB\-font\fR and
 118 \fB\-command\fR configuration options in per\-widget \fB<FocusIn>\fR handlers
 119 (and if necessary to unset them \- i.e. set to the empty string \- in
 120 corresponding \fB<FocusOut>\fR handlers). This is particularly important for
 121 implementers of library code using the font selection dialog, to avoid
 122 conflicting with application code that may also want to use the dialog.
 123 .PP
 124 Because the font selection dialog is application-global, in the presence of
 125 multiple interpreters calling \fBtk fontchooser\fR, only the \fB\-command\fR
 126 callback set by the interpreter that most recently called \fBtk fontchooser\fR
 127 \fBconfigure\fR or \fBtk fontchooser\fR \fBshow\fR will be invoked in response
 128 to user action and only the \fB\-parent\fR set by that interpreter will receive
 129 \fB<<TkFontchooser*>>\fR virtual events.
 130 .PP
 131 The font dialog implementation may only store (and return) \fBfont\fR
 132 \fBactual\fR data as the value of the \fB\-font\fR configuration option. This
 133 can be an issue when \fB\-font\fR is set to a named font, if that font is
 134 subsequently changed, the font dialog \fB\-font\fR option needs to be set again
 135 to ensure its selected font matches the new value of the named font.
 136 .PP
 137 .SH EXAMPLE
 138 .PP
 139 .CS
 140 proc fontchooserDemo {} {
 141     wm title . "Font Chooser Demo"
 142     \fBtk fontchooser\fR \fBconfigure\fR \-parent .
 143     button .b \-command fontchooserToggle \-takefocus 0
 144     fontchooserVisibility .b
 145     bind . \fB<<TkFontchooserVisibility>>\fR \\
 146             [list fontchooserVisibility .b]
 147     foreach w {.t1 .t2} {
 148         text $w \-width 20 \-height 4 \-borderwidth 1 \-relief solid
 149         bind $w <FocusIn> [list fontchooserFocus $w]
 150         $w insert end "Text Widget $w"
 151     }
 152     .t1 configure \-font {Courier 14}
 153     .t2 configure \-font {Times 16}
 154     pack .b .t1 .t2; focus .t1
 155 }
 156 proc fontchooserToggle {} {
 157     \fBtk fontchooser\fR [expr {
 158             [\fBtk fontchooser\fR \fBconfigure\fR \-visible] ?
 159             "\fBhide\fR" : "\fBshow\fR"}]
 160 }
 161 proc fontchooserVisibility {w} {
 162     $w configure \-text [expr {
 163             [\fBtk fontchooser\fR \fBconfigure\fR \-visible] ?
 164             "Hide Font Dialog" : "Show Font Dialog"}]
 165 }
 166 proc fontchooserFocus {w} {
 167     \fBtk fontchooser\fR \fBconfigure\fR \-font [$w cget \-font] \\
 168             \-command [list fontchooserFontSelection $w]
 169 }
 170 proc fontchooserFontSelection {w font args} {
 171     $w configure \-font [font actual $font]
 172 }
 173 fontchooserDemo
 174 .CE
 175 .SH "SEE ALSO"
 176 font(n), tk(n)
 177 .SH KEYWORDS
 178 dialog, font, font selection, font chooser, font panel
 179 '\" Local Variables:
 180 '\" mode: nroff
 181 '\" End: