ask-user-for-font

Function

Package: common-graphics

Arguments: &key stream-for-font initial-font fixed-width-only-p minimum-size maximum-size initial-point-size stream

Pops up the Windows Common Dialog for font selection. This function is also used internally by Allegro CL for font selection. If a font is selected, two values are returned: the font selected and the point size specified by the user. (See below for why the point size might be useful.) If s/he cancels, the single value nil is returned.

The arguments are as follows:

initial-font: if passed, should be a font object to be displayed initially in the dialog; if not passed, then no initial font is displayed.
fixed-width-only-p: if true, then the choices displayed in the dialog will be only those fonts where every character is the same width, such as :courier.
minimum-size: if passed, should be a positive integer denoting the minimum acceptable point size of the font; all sizes are still listed in the dialog, but a pop-up error dialog will prevent the user from returning an unacceptable size.
maximum-size: if passed, should be a positive integer denoting the maximum acceptable point size of the font.
initial-point-size: If passed, overrides the pixel-size of the font indicated in the initial-font. This parameter is supplied because the font dialog displays sizes in points, and it is difficult to automatically map a common graphics pixel size to the desired point size for display.
stream: the owning window of the font dialog. All owned windows of this window will be unavailable to the end user while the font dialog is being invoked.
stream-for-font: The list of font choices displayed on the dialog will be the set of fonts available for this stream. If the selected font is to be used in a window, then the default value of (screen *system*) should be appropriate. But if the selected font is to be used on a printer stream, then you may want to pass the printer stream as the value of this argument so that the list of choices will include fonts provided by the printer driver.

When selecting a font, one potential source of confusion is that while Allegro CL specifies font sizes in pixels, the Common Dialog specifies them in points. So the size that you select from the dialog will not be the same as the size value in the returned font object. But the point size specified will be returned as the second returned value -- see the next paragraph. Allegro CL uses pixel-size programmatically so that the same units are used for all sizes associated with a window --fonts, window dimensions, drawing, etc. The point sizes that appear in the Common Dialog, on the other hand, will be similar to those that are familiar from choosing fonts interactively in other applications.

The point size is provided as the second returned value to permit better communication with users. Suppose a user of your application is presented with the dialog displayed by this function and asked to choose a font for use in some table of data that the application will display. Suppose further that the program determines that the font chosen is so large that it will cause line truncation or wrapping. A dialog might be displayed telling the user that the chosen font will cause problems and that s/he might wish to choose a smaller font. Mentioning the point size in that dialog will be more meaningful to users (because it corresponds to the value they actually chose) than mentioning the pixel size, which is a value they likely will not have seen. Note that both the point size and the pixel size are contained in the Windows font structure, from which Allegro CL gets all font information. Allegro CL does not itself derive a pixel size from the point size.

Common Graphics and IDE documentation is described in About Common Graphics and IDE documentation in cgide.htm.

The documentation is described in introduction.htm and the index is in index.htm.

Created 2000.10.5.