Set/retrieve font information on Windows
|
WTSupported in traditional Synergy on Windows
|
|
|
|
return = %U_WNDFONT(subfunction, arg[, ...])
or
xcall U_WNDFONT(subfunction, arg[, ...])
Return value
return
On Windows, a value specific to the subfunction. On UNIX and OpenVMS, always returns false, except for D_SETWNDFONT, which returns true if successful. (^VAL)
Arguments
subfunction
The specific font function to perform: (n)
Enable/disable automatic font switching.
Display font selection dialog.
Enumerate font palette entries.
Retrieve the font handle for a font palette entry.
Retrieve the font palette entry for a font handle.
Retrieve font size information.
Retrieve font palette information.
Retrieve the application scaling percentage.
Retrieve the font palette entry for a window.
Save font palette information in synergy.ini or synuser.ini.
Set font palette information.
Set the application scaling percentage.
Set the font palette entry for a window.
arg
One or more arguments, depending on subfunction.
Discussion
%U_WNDFONT sets or retrieves font information in a Windows environment. It also enables you to display a standard Microsoft Font dialog box. See the individual subfunctions for details.
The Synergy runtime manages font information by maintaining a font palette. A font palette consists of font palette entries, each of which associates a font name with a typeface, point size, and sizing character combination. Font palette entries can be added or modified using %U_WNDFONT.
%U_WNDFONT can be used to change the font for an application by assigning a different font palette entry name to the global and/or alternate fonts.
An application window defined as less than 132 columns uses the “global font.” An application window defined as 132 columns or more, or one changed to this size, uses the “alternate font.” This enables an application window having a greater number of columns to use a different font and, consequently, still fit the entire window on the screen.
%U_WNDFONT can also be used to change the font for a specific window.
Each time the font is changed, the application (or window) is completely updated to use the new font.
See also
- Using fonts on Windows
- I_FLDMOD and IB_FIELD routines for information on changing a field or prompt font
prev_flag = %U_WNDFONT(D_ALTFONT132, alt_font_flag)
or
xcall U_WNDFONT(D_ALTFONT132, alt_font_flag)
Return value
prev_flag
The previous value of alt_font_flag. (^VAL)
Arguments
alt_font_flag
A flag that specifies if automatic switching to/from the alternate font is enabled. (n)
TRUE = Enable automatic font switching. (default)
FALSE = Disable automatic font switching.
Discussion
The D_ALTFONT132 subfunction of %U_WNDFONT enables/disables automatic font switching.
If alt_font_flag is true, then whenever the number of columns in the application window crosses the 132 column boundary, the font will automatically switch to or from the “alternate” font. If alt_font_flag is false, automatic font switching will not occur.
See also
status = %U_WNDFONT(D_CHOOSEFONT, face_name, point_size, [sizing_char], [include_prop], & [help_filename], [help_context_id][, title])
or
xcall U_WNDFONT(D_CHOOSEFONT, face_name, point_size, [sizing_char], [include_prop], & [help_filename], [help_context_id][, title])
Return value
status
True if the user selected a font; otherwise false. (^VAL)
Arguments
face_name
The name of the Windows font. (a)
point_size
The size of the Windows font. (n)
sizing_char
(optional) The sizing character. (a)
include_prop
(optional) The flag to include proportional fonts. (n)
help_filename
(optional) The name of the help file. (a)
help_context_id
(optional) The context identifier for help. Required if help_filename is passed. (n)
title
(optional) The title for the dialog box. (a)
Discussion
The D_CHOOSEFONT subfunction of %U_WNDFONT displays a Microsoft Windows Font dialog box. Any values passed in face_name, point_size, and sizing_char are used as the typeface, point size, and sizing character initially displayed in the dialog box. Face_name and sizing_char are case sensitive.
If the user makes a selection, face_name, point_size, and sizing_char are returned with the typeface name, size, and sizing character values.
D_CHOOSEFONT does not set the new font or update synergy.ini or synuser.ini. To set the new font, use D_SETFONT. To explicitly update synergy.ini or synuser.ini, use D_SAVEFONT.
If sizing_char is not present, the sizing character cannot be modified and defaults to an uppercase “A”. The sizing character is a single letter used to determine the cell size for proportional fonts within a visual object for the purposes of positioning. When you specify sizing_char to be “W”, for example, the object will be significantly wider than an object with a sizing character of “i”. The sizing character is case sensitive.
If include_prop is true, proportional fonts are included in the list of available typefaces for the dialog box. The default include_prop value is false.
If help_filename is passed, the dialog will have a Help button. Help_filename can be the name of either a WinHelp file (.hlp) or an HTML Help file (.chm):
- If the file extension is .hlp, help_context_id is passed as a context number to the HELP_CONTEXT command for the WinHelp API. See the Microsoft documentation for WinHelp for more information on this command.
- If the file extension is .chm, the HtmlHelp API is used, and help_context_id is passed on to the HTML Help API command HH_HELP_CONTEXT. See the Microsoft documentation for the HTML Help API for more information on this command.
If title is not passed, the default title for the dialog box is “Font.”
Examples
The following example displays a dialog box, entitled “Select Font,” with the font name typeface, the font size size, and sizing character char, specified.
success = %u_wndfont(D_CHOOSEFONT, typeface, size, char, TRUE,,,"Select Font")
Compare the previous example with the following example, which neither includes proportional fonts nor prompts for a sizing character, but includes a help button on the dialog box.
success = %u_wndfont(D_CHOOSEFONT, font, size,,, "helpfile.hlp", select_font_id, "Select Font")
num_palette = %U_WNDFONT(D_ENUMFONTS, [DF_BY_HANDLE|DF_BY_NAME], & [maximum], [hndl_array] [, name_array])
or
xcall U_WNDFONT(D_ENUMFONTS, [DF_BY_HANDLE|DF_BY_NAME], [maximum], [hndl_array] [, name_array])
Return value
num_palette
The total number of defined font palette entries. (^VAL)
Arguments
DF_BY_HANDLE | DF_BY_NAME
(optional) Order by handle (default) or order by name. (n)
maximum
(optional) The maximum number of fonts to return in the arrays. (n)
hndl_array
(optional) First element of the returned array of font handles. (n)
name_array
(optional) First element of the returned array of font palette entry names. (n)
Discussion
The D_ENUMFONTS subfunction of %U_WNDFONT returns font information for the fonts that are currently defined.
If maximum is not passed, it defaults to zero. This returns the number of font palette entries, and any arrays that might be passed are ignored. Because the number of defined fonts has no logical limit, D_ENUMFONTS can be first called with maximum not passed (or 0) to retrieve the number of font palette entries. and then the desired array(s) can be allocated accordingly.
The return value is always the total number of defined fonts, even if maximum is less than this value. The number of items returned in the arrays is the lesser of the return value or maximum.
We recommend that the size of each array entry in hndl_array be an i4 for efficiency and to guarantee that the full handle value will be returned.
If the size of each array entry in name_array is less than 60 characters, some font palette entry names may be truncated.
Examples
The following example returns the total number of fonts defined in numfonts and the first 100 palette entry names in font_array.
numfonts = %u_wndfont(D_ENUMFONTS, DF_BY_NAME, 100,, font_array)
font_hndl = %U_WNDFONT(D_FONTHANDLE, palette_name)
Return value
font_hndl
The handle to the specified font. (^VAL)
Arguments
palette_name
The name of a font palette entry or one of the following: (a or n)
DF_CURRENT = Current font.
DF_DEFAULT = Global font.
DF_ALTERNATE = Alternate global font.
DF_DEBUGGER = Debugger font.
Discussion
The D_FONTHANDLE subfunction of %U_WNDFONT returns the font handle for a specified font palette entry name. Using handles is more efficient than using font palette entry names, however, font names are more persistent.
See also
D_FONTNAME subfunction for more information on retrieving a font palette entry name.
Examples
The following example returns the font handle in hndl for the font “font_name.”
hndl = %u_wndfont(D_FONTHANDLE, "font_name")
status = %U_WNDFONT(D_FONTNAME, font_hndl, palette_name)
or
xcall U_WNDFONT(D_FONTNAME, font_hndl, palette_name)
Return value
status
True if successful, or false if not. (^VAL)
Arguments
font_hndl
The handle to the font. (n)
palette_name
The returned font palette entry name. (a)
Discussion
The D_FONTNAME subfunction of %U_WNDFONT retrieves the font palette entry name for a specified font handle. Font palette entry names are more persistent than font handles, however, using font handles is more efficient.
See also
D_FONTHANDLE subfunction for more information on returning a font handle
Examples
The following example returns the name of the font in name that is specified by the font handle hndl.
success = %u_wndfont(D_FONTNAME, hndl, name)
status = %U_WNDFONT(D_FONTSIZE, font_name, width, height)
or
xcall U_WNDFONT(D_FONTSIZE, font_name, width, height)
Return value
status
On Windows, true. On UNIX and OpenVMS, false. (^VAL)
Arguments
font_name
The name of a font palette entry, a font handle, or one of the following: (a or n)
DF_CURRENT = Current font.
DF_DEFAULT = Global font.
DF_ALTERNATE = Alternate global font.
DF_DEBUGGER = Debugger font.
width
The returned width of the sizing character for the font palette entry. (n)
height
The returned height of the sizing character for the font palette entry. (n)
Discussion
The D_FONTSIZE subfunction of %U_WNDFONT returns font size information (height and width) for a given Synergy font palette entry. This size is given as the number of pixels used on the screen. Note that this may differ from the same font’s size when sent to a printer.
Examples
The following example returns the width and height of the font palette entry specified by font_entry.
success = %u_wndfont(D_FONTSIZE, font_entry, font_width, font_height)
font_hndl = %U_WNDFONT(D_GETFONT, font_id, [face_name], [point_size], [sizing_char] & [, palette_name])
or
xcall U_WNDFONT(D_GETFONT, font_id, [face_name], [point_size], [sizing_char] & [, palette_name])
Return value
font_hndl
The font handle if the font request was successful, or false if it was not. (^VAL)
Arguments
font_id
The name of a font palette entry, a font handle, or one of the following: (a or n)
DF_CURRENT = Current font.
DF_DEFAULT = Global font.
DF_ALTERNATE = Alternate global font.
DF_DEBUGGER = Debugger font.
face_name
(optional) The name of the Windows font. (a)
point_size
(optional) The size of the Windows font. (n)
sizing_char
(optional) The sizing character. (a)
palette_name
(optional) The returned font palette entry name. (a)
Discussion
The D_GETFONT subfunction of %U_WNDFONT retrieves the current typeface, point size, and sizing character of a specific font palette entry or of the current, global, alternate, or debugger font.
Note that D_GETFONT does not use the application scaling percentage (see D_GETSCALE). To get the approximate visual point size for a font used in an application, multiply the point size (returned by D_GETFONT) by the application scaling percentage (returned by D_GETSCALE) and then divide by 100. For example if the size returned by D_GETFONT is 12, and the application scaling percentage is 150, the visual point size is 18 (that is, 12 * 150 / 100 = 18).
See also
D_SETFONT subfunction for a description of sizing_char
The following example returns the name and size of the font specified by fontid in face_name and point_size. The font palette entry name is returned in palette_name, and the default sizing character is returned in size_char.
sts = %u_wndfont(D_GETFONT, fontid, face_name, point_size, size_char, palette_name)
scaling_percentage = %U_WNDFONT(D_GETSCALE)
Return value
scaling_percentage
The application scaling percentage. (^VAL)
Discussion
The D_GETSCALE subfunction of %U_WNDFONT returns the application scaling percentage, which is a percentage of the default size of the application. See D_SETSCALE for more information.
Note that when using a proportionally spaced font for the application window, D_GETSCALE may not return 100 initially when SYN_RESIZE_SCALE is set.
status = %U_WNDFONT(D_GETWNDFONT, window_id[, palette_name])
or
xcall U_WNDFONT(D_GETWNDFONT, window_id[, palette_name])
Return value
status
On Windows, the handle of the font requested if successful, or false if not. On UNIX and OpenVMS, always returns false (0). (^VAL)
Arguments
window_id
The ID of the window whose font is being retrieved. (n)
palette_name
(optional) The returned font palette entry name. (a)
Discussion
The D_GETWNDFONT subfunction of %U_WNDFONT retrieves the name of the font palette entry applied to a general window or input window.
On UNIX and OpenVMS, D_GETWNDFONT, palette_name returns the name of the font palette entry if it is defined.
See also
Examples
The following example returns the font handle and font palette entry name for the window specified by wndid.
hndl = %u_wndfont(D_GETWNDFONT, wndid, name)
status = %U_WNDFONT(D_SAVEFONT, [font_id][, all_users])
or
xcall U_WNDFONT(D_SAVEFONT, [font_id][, all_users])
Return value
status
On Windows, true if the function is successful, or false if it was not. On UNIX and OpenVMS, always returns false. (^VAL)
Arguments
font_id
(optional) The name of a font palette entry, a font handle, or one of the following: (a or n)
DF_CURRENT = Current font.
DF_DEFAULT = Global font.
DF_ALTERNATE = Alternate global font.
DF_DEBUGGER = Debugger font.
all_users
(optional) One of the following: (n)
TRUE = Save font palette entry information to synergy.ini.
FALSE = Save font palette entry information to synuser.ini. (default)
Discussion
The D_SAVEFONT subfunction of %U_WNDFONT saves the current font palette entry information for the specified font_id by writing it to the [fonts] section of synergy.ini or synuser.ini. If the function fails, which causes status to be returned as false, you can use %SYSERR to retrieve the system-specific error code.
If font_id is not passed, all font palette entries are saved.
If automatic font switching has been turned off using the D_ALTFONT132 subfunction, then DF_CURRENT is the same as DF_DEFAULT.
font_hndl = %U_WNDFONT(D_SETFONT, font_id, [face_name], [point_size][, sizing_char])
or
xcall U_WNDFONT(D_SETFONT, font_id, [face_name], [point_size][, sizing_char])
Return value
font_hndl
The font handle if the font request was successful, or false if it was not. (^VAL)
Arguments
font_id
The name of a font palette entry, a font handle, or one of the following: (a or n)
DF_CURRENT = Current font.
DF_DEFAULT = Global font.
DF_ALTERNATE = Alternate global font.
DF_DEBUGGER = Debugger font.
face_name
(optional) The name of the Windows font. (a)
point_size
(optional) The size of the Windows font. If omitted or passed as 0, defaults to 10. (n)
sizing_char
(optional) The sizing character. (a)
Discussion
The D_SETFONT subfunction of %U_WNDFONT defines or modifies a font palette entry at runtime. This font information is not saved in synergy.ini until the %U_WNDFONT subfunction, D_SAVEFONT, is called.
When defining a new font palette entry, specify font_id as either the font palette entry name or one of the literals listed above. You are returned the font handle. When modifying an existing font palette entry, you can refer to it (using font_id) by font handle.
Face_name is case sensitive. If it is omitted or is passed as blank, it defaults to the name of the current default font. If a proportional font is passed as face_name, sizing_char (a single letter) is used to determine the cell size within a visual object for the purposes of positioning. For example, “W” results in a cell size that is significantly wider than with “i”. The sizing character is case sensitive and, if omitted or passed as %char(0), defaults to “A”.
Examples
The following examples set the font palette entry specified by “my_font” to 10-point Courier typeface.
sts = %u_wndfont(D_SETFONT, "my_font", Courier, 10) sts = %u_wndfont(D_SETFONT, "my_font", Courier)
The following sets the current font to 12-point Arial typeface with a “q” sizing character.
sts = %u_wndfont(D_SETFONT, DF_CURRENT, "Arial", 12, "q")
status = %U_WNDFONT(D_SETSCALE, scaling_percentage)
or
xcall U_WNDFONT(D_SETSCALE, scaling_percentage)
Return value
status
On Windows, true. On UNIX and OpenVMS, false. (^VAL)
Arguments
scaling_percentage
The application scaling percentage. This can be specified as a whole number or with fractional precision (e.g., 176 or 50.95). Passing 100 sets the scaling percentage to 100 (no scaling). (n)
Discussion
The D_SETSCALE subfunction of %U_WNDFONT changes the size of the application display screen, windows for the application, and characters in those windows. It changes the height and the width of these items by the percentage passed as scaling_percentage. For example, passing 200 increases the height and width of these items by 200%. Note, however, that characters don’t always scale evenly; they are sized as large as possible without exceeding the specified percentage in either direction.
|
For best results, use OpenType or TrueType fonts. D_SETSCALE’s effectiveness is dependent on how well the font used for windows in the application can be scaled. If the font doesn’t scale well, D_SETSCALE will not be able to correctly scale the display screen, windows for the application, or characters on those windows. For example, Fixedsys (which is the default font for Toolkit applications on Windows in traditional Synergy) doesn’t scale well and will prevent D_SETSCALE from working correctly. The following will not scale: message boxes, menu bars, toolbars, buttons, ActiveX controls, and Windows common controls (e.g., the Color, Font, Open, and Print Preview dialog boxes). |
See also
- APP_SCALE environment variable for information on the default scaling percentage
- D_GETSCALE subfunction
- Resizing the application
status = %U_WNDFONT(D_SETWNDFONT, window_id, font_id)
or
xcall U_WNDFONT(D_SETWNDFONT, window_id, font_id)
Return value
status
True if the font request was successful, or false if it was not. (^VAL)
Arguments
window_id
The ID of the window whose font is being set. (n)
font_id
The name of a font palette entry, a font handle, or one of the following: (a or n)
DF_CURRENT = Current font.
DF_DEFAULT = Global font.
DF_ALTERNATE = Alternate global font.
DF_DEBUGGER = Debugger font.
Discussion
The D_SETWNDFONT subfunction of %U_WNDFONT modifies the font for a general window or input window at runtime. If a proportional font is specified, objects within that window that do not support proportional fonts may not display as expected.
If font_id is invalid, the behavior of D_SETWNDFONT depends on the argument type. If font_id is numeric, an “invalid font id” error is generated. If font_id is alphanumeric, no error is generated, and the application window’s font is used.
While it does not visually render the font on UNIX or OpenVMS systems, D_SETWNDFONT does preserve the font information in the window (when the window is saved with U_SAVE) so that it can be used later on Windows.
See also
The following example sets the font for the window specified by wndid to be “my_input_font.”
success = %u_wndfont(D_SETWNDFONT, wndid, "my_input_font")
