TIP #324 Version 1.3: A Standard Dialog For Font Selection

This is not necessarily the current version of this TIP.

Abstract

This TIP proposes a new command that pops up a dialog box that allows the selection of a font. Where possible, this dialog will be implemented using the host platform's standard dialogs.

Rationale

A number of platforms (Windows and MacOSX) have standard dialogs for common user-oriented tasks, and Tk provides an interface to these dialogs through commands such as tk_getOpenFile and tk_chooseColor. However, another dialog that they provide and which some programs would find useful is a font selector. This TIP proposes adding a command to do just that; where a platform does not provide such a standard dialog, one implemented using a Tcl script will be used instead.

Proposal

Tk shall have a new command, tk_chooseFont, with the syntax described below.

The dialog will not return a result as on some platforms (MacOSX) this is required to be modeless while on others (Windows) it must be modal. Therefore all actions will be done via a configured command prefix registered with tk_chooseFont configure -command. In the modal case clicking either the Apply button (if present) or the OK button will cause the command prefix to be called with the font specification appended as an additional argument. If Cancel is chosen, or the dialog is closed manually on platforms that permit this, this will be called with an empty string. (It will not be so called otherwise.)

• tk_chooseFont configure ?-option value ...?

  Read or set (for all but 'visible' option) one or more of the following options.

  -parent -- This specifies the parent window of the dialog (similarly to the -parent option to other dialogs).

  -title -- This specifies the title of the dialog. If the platform specific dialog cannot support this then the option is ignored.

  -font -- This specifies the font shown in the dialog in any form given on the font(n) manual page (section "FONT DESCRIPTION"). Provided it is supported by the platform implementation this font will be selected when the dialog is displayed.

  -command -- This specifies a command prefix to be called when a font selection has been made by the user. The command will have the font specification appended as the final parameter and is then evaluated in the global namespace. The font specification will be a list of the form described on the font(n) manual page under "FONT DESCRIPTION" section 3. That is a list of {family size style ?style ...?}. For platform dialogs offering the user additional control over font style (e.g., color, overstrike, underline), these may be passed as an optional, second string argument.

  This command will be called with an empty string if the user closes the dialog (either by a Cancel button, close button, or other means. (It will never be called with an empty string otherwise.)

  -visible -- This read-only option returns a boolean indicating whether the font dialog is currently being displayed. Setting it has no effect.

• tk_chooseFont hide

  Hides the font dialog if it is currently being shown and exits modal loop if dialog is modal on platform. Returns the empty string. A <<TkChoosefontVisibility>> virtual event is sent to the parent window.

• tk_chooseFont show

  Shows the font dialog if it is currently hidden, and begins a modal loop if dialog is modal on platform. On these platforms, this call returns when modal loop as exited. Returns the empty string. A <<TkChoosefontVisibility>> virtual event is sent to the parent window.

The <<TkChoosefontVisibility>> virtual event is sent whenever the font panel is displayed or withdrawn. Nothing in the event specifies which of these is the case, however; it is necessary to query tk_chooseFont configure -visible to know.

Whenever a platform provides a suitable font dialog in its own API, Tk should not use a script-based alternative, even if this means missing out on features like the title or dynamic updating of the font during the selection process.

Application code should expect that the command prefix registered with tk_chooseFont configure -command will be called any time the user selects a font, even on platforms where the dialog is modal.

Implementors of libraries should be careful when setting -command and -font options and should endeavor to do this only in FocusIn handlers, restoring previous state in FocusOut handlers, to avoid interfering with user code.

When multiple interpreters are active, only the command callback set in the interpreter that most recently called tk_chooseFont configure -command or tk_chooseFont show will be called when the user makes a font selection.

Reference Implementation

See Tk Patch 1477426 [1]

and later revisions posted on the Tcl-Core thread [2]

Copyright

This document has been placed in the public domain.

This is not necessarily the current version of this TIP.