diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/fontchooser.n | 183 | ||||
| -rw-r--r-- | doc/tk.n | 44 |
2 files changed, 207 insertions, 20 deletions
diff --git a/doc/fontchooser.n b/doc/fontchooser.n new file mode 100644 index 0000000..6e3a766 --- /dev/null +++ b/doc/fontchooser.n @@ -0,0 +1,183 @@ +'\" +'\" Copyright (c) 2008 Daniel A. Steffen <das@users.sourceforge.net> +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: @(#) $Id: fontchooser.n,v 1.1 2008/12/10 05:02:40 das Exp $ +'\" +.so man.macros +.TH fontchooser n "" Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +fontchooser \- control font selection dialog +.SH SYNOPSIS +\fBtk fontchooser\fR \fBconfigure\fR ?\fI\-option value \-option value ...\fR? +.sp +\fBtk fontchooser\fR \fBshow\fR +.sp +\fBtk fontchooser\fR \fBhide\fR +.BE +.SH DESCRIPTION +.PP +The \fBtk fontchooser\fR command controls the Tk font selection dialog. It uses +the native platform font selection dialog where available, or a dialog +implemented in Tcl otherwise. +.PP +Unlike most of the other Tk dialog commands, \fBtk fontchooser\fR does not +return an immediate result, as on some platforms (Mac OS X) the standard font +dialog is modeless while on others (Windows) it is modal. To accommodate this +difference, all user interaction with the dialog will be communicated to the +caller via callbacks or virtual events. +.PP +The \fBtk fontchooser\fR command can have one of the following forms: +.TP +\fBtk fontchooser\fR \fBconfigure \fR?\fI\-option value \-option value ...\fR? +. +Set or query one or more of the configurations options below (analogous to Tk +widget configuration). +.TP +\fBtk fontchooser\fR \fBshow\fR +. +Show the font selection dialog. Depending on the platform, may return +immediately or only once the dialog has been withdrawn. +.TP +\fBtk fontchooser\fR \fBhide\fR +. +Hide the font selection dialog if it is visible and cause any pending +\fBtk fontchooser\fR \fBshow\fR command to return. +.PP +.SH "CONFIGURATION OPTIONS" +.TP +\fB\-parent\fR +Specifies/returns the logical parent window of the font selection dialog +(similar to the \fB\-parent\fR option to other dialogs). The font selection +dialog is hidden if it is visible when the parent window is destroyed. +.TP +\fB\-title\fR +Specifies/returns the title of the dialog. Has no effect on platforms where the +font selection dialog does not support titles. +.TP +\fB\-font\fR +Specifies/returns the font that is currently selected in the dialog if it is +visible, or that will be initially selected when the dialog is shown (if +supported by the platform). Can be set to the empty string to indicate that no +font should be selected. Fonts can be specified in any form given by the "FONT +DESCRIPTION" section in the \fBfont\fR manual page. +.TP +\fB\-command\fR +Specifies/returns the command prefix to be called when a font selection has +been made by the user. The command prefix is evaluated at the global level +after having the specification of the selected font appended. On platforms +where the font selection dialog offers the user control of further font +attributes (such as color), additional key/value pairs may be appended before +evaluation. Can be set to the empty string to indicate that no callback should +be invoked. Fonts are specified by a list of form [3] of the "FONT DESCRIPTION" +section in the \fBfont\fR manual page (i.e. a list of the form +\fI{family size style ?style ...?}\fR). +.TP +\fB\-visible\fR +Read-only option that returns a boolean indicating whether the font selection +dialog is currently visible. Attempting to set this option results in an error. + +.PP +.SH "VIRTUAL EVENTS" +.TP +\fB<<TkFontchooserVisibility>>\fR +Sent to the dialog parent whenever the visibility of the font selection dialog +changes, both as a result of user action (e.g. disposing of the dialog via +OK/Cancel button or close box) and of the \fBtk fontchooser\fR +\fBshow\fR/\fBhide\fR commands being called. Binding scripts can determine the +current visibility of the dialog by querying the \fB\-visible\fR configuration +option. +.TP +\fB<<TkFontchooserFontChanged>>\fR +Sent to the dialog parent whenever the font selection dialog is visible and the +selected font changes, both as a result of user action and of the \fB\-font\fR +configuration option being set. Binding scripts can determine the currently +selected font by querying the \fB\-font\fR configuration option. +.PP +.SH NOTES +.PP +Callers should not expect a result from \fBtk fontchooser\fR \fBshow\fR and may +not assume that the dialog has been withdrawn or closed when the command +returns. All user interaction with the dialog is communicated to the caller via +the \fB\-command\fR callback and the \fB<<TkFontchooser*>>\fR virtual events. +It is implementation dependent which exact user actions result in the callback +being called resp. the virtual events being sent. Where an Apply or OK button +is present in the dialog, that button will trigger the \fB\-command\fR callback +and \fB<<TkFontchooserFontChanged>>\fR virtual event. On some implementations +other user actions may also have that effect; on Mac OS X for instance, the +standard font selection dialog immediately reflects all user choices to the +caller. +.PP +In the presence of multiple widgets intended to be influenced by the font +selection dialog, care needs to be taken to correctly handle focus changes: the +font selected in the dialog should always match the current font of the widget +with the focus, and the \fB\-command\fR callback should only act on the widget +with the focus. The recommended practice is to set font dialog \fB\-font\fR and +\fB\-command\fR configuration options in per\-widget \fB<FocusIn>\fR handlers +(and if necessary to unset them \- i.e. set to the empty string \- in +corresponding \fB<FocusOut>\fR handlers). This is particularly important for +implementors of library code using the font selection dialog, to avoid +conflicting with application code that may also want to use the dialog. +.PP +Because the font selection dialog is application-global, in the presence of +multiple interpreters calling \fBtk fontchooser\fR, only the \fB\-command\fR +callback set by the interpreter that most recently called \fBtk fontchooser\fR +\fBconfigure\fR or \fBtk fontchooser\fR \fBshow\fR will be invoked in response +to user action and only the \fB\-parent\fR set by that interpreter will receive +\fB<<TkFontchooser*>>\fR virtual events. +.PP +The font dialog implementation may only store (and return) \fBfont\fR +\fBactual\fR data as the value of the \fB\-font\fR configuration option. This +can be an issue when \fB\-font\fR is set to a named font, if that font is +subsequently changed, the font dialog \fB\-font\fR option needs to be set again +to ensure its selected font matches the new value of the named font. +.PP +.SH EXAMPLE +.PP +.CS +proc fontchooserDemo {} { + wm title . "Font Chooser Demo" + \fBtk fontchooser\fR \fBconfigure\fR \-parent . + button .b \-command fontchooserToggle \-takefocus 0 + fontchooserVisibility .b + bind . \fB<<TkFontchooserVisibility>>\fR \\ + [list fontchooserVisibility .b] + foreach w {.t1 .t2} { + text $w \-width 20 \-height 4 \-borderwidth 1 \-relief solid + bind $w <FocusIn> [list fontchooserFocus $w] + $w insert end "Text Widget $w" + } + .t1 configure \-font {Courier 14} + .t2 configure \-font {Times 16} + pack .b .t1 .t2; focus .t1 +} +proc fontchooserToggle {} { + \fBtk fontchooser\fR [expr { + [\fBtk fontchooser\fR \fBconfigure\fR \-visible] ? + "\fBhide\fR" : "\fBshow\fR"}] +} +proc fontchooserVisibility {w} { + $w configure \-text [expr { + [\fBtk fontchooser\fR \fBconfigure\fR \-visible] ? + "Hide Font Dialog" : "Show Font Dialog"}] +} +proc fontchooserFocus {w} { + \fBtk fontchooser\fR \fBconfigure\fR \-font [$w cget \-font] \\ + \-command [list fontchooserFontSelection $w] +} +proc fontchooserFontSelection {w font args} { + $w configure \-font [font actual $font] +} +fontchooserDemo +.CE +.SH "SEE ALSO" +font(n), tk(n) +.SH KEYWORDS +dialog, font, font selection, font chooser, font panel +'\" Local Variables: +'\" mode: nroff +'\" End: @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: tk.n,v 1.20 2008/10/18 14:22:21 dkf Exp $ +'\" RCS: @(#) $Id: tk.n,v 1.21 2008/12/10 05:02:40 das Exp $ '\" .so man.macros .TH tk n 8.4 Tk "Tk Built-In Commands" @@ -66,6 +66,28 @@ format. \fI\-x\fR and \fI\-y\fR represent window-relative coordinates, and \fI\-height\fR is the height of the current cursor location, or the height of the specified \fIwindow\fR if none is given. .TP +\fBtk inactive \fR?\fB\-displayof \fIwindow\fR? ?\fBreset\fR? +. +Returns a positive integer, the number of milliseconds since the last +time the user interacted with the system. If the \fB\-displayof\fR +option is given then the return value refers to the display of +\fIwindow\fR; otherwise it refers to the display of the application's +main window. +.RS +.PP +\fBtk inactive\fR will return \-1, if querying the user inactive time +is not supported by the system, and in safe interpreters. +.PP +If the literal string \fBreset\fR is given as an additional argument, +the timer is reset and an empty string is returned. Resetting the +inactivity time is forbidden in safe interpreters and will throw and +error if tried. +.RE +.TP +\fBtk fontchooser \fIsubcommand\fR ... +Controls the Tk font selection dialog. For more details see the +\fBfontchooser\fR manual page. +.TP \fBtk scaling \fR?\fB\-displayof \fIwindow\fR? ?\fInumber\fR? . Sets and queries the current scaling factor used by Tk to convert between @@ -91,24 +113,6 @@ is undefined whether existing widgets will resize themselves dynamically to accommodate the new scaling factor. .RE .TP -\fBtk inactive \fR?\fB\-displayof \fIwindow\fR? ?\fBreset\fR? -. -Returns a positive integer, the number of milliseconds since the last -time the user interacted with the system. If the \fB\-displayof\fR -option is given then the return value refers to the display of -\fIwindow\fR; otherwise it refers to the display of the application's -main window. -.RS -.PP -\fBtk inactive\fR will return \-1, if querying the user inactive time -is not supported by the system, and in safe interpreters. -.PP -If the literal string \fBreset\fR is given as an additional argument, -the timer is reset and an empty string is returned. Resetting the -inactivity time is forbidden in safe interpreters and will throw and -error if tried. -.RE -.TP \fBtk useinputmethods \fR?\fB\-displayof \fIwindow\fR? ?\fIboolean\fR? . Sets and queries the state of whether Tk should use XIM (X Input Methods) @@ -125,7 +129,7 @@ Returns the current Tk windowing system, one of \fBx11\fR (X11-based), \fBwin32\fR (MS Windows), or \fBaqua\fR (Mac OS X Aqua). .SH "SEE ALSO" -busy(n), send(n), winfo(n) +busy(n), fontchooser(n), send(n), winfo(n) .SH KEYWORDS application name, send '\" Local Variables: |