Fnt Library v3.0

Summary
Fnt Library v3.0
IntroductionFonts are logical objects that instruct the computer how to draw text on a device (display, printers, plotters, etc.)
AutoHotkey CompatibilityANSI, Unicode, and Unicode 64-bit.
Common ParametersCommon function parameters of note.
Terminology
Issues and Considerations
Differences from AutoHotkeyThis library attempts to emulate AutoHotkey behavior when possible but there are a few notable exceptions.
DPI-AwareThe functions in this library are not DPI-aware.
Font FamilyFor fonts used in Windows, a font family is the font or group of fonts that represent a particular typeface.
Font Family [Secondary Definition]Font families describe the look of a font in a general way.
Font HeightStarting with v3.0, a font created using the Fnt library can be created with a specific height.
Global VariablesThis library uses a few global variables.
Measuring Text SizeVersion 3.0 of the library introduces changes to how text can be measured.
Non-Client FontsNon-Client (sometimes written as “nonclient”) fonts are the fonts used by the caption (text on the title bar), small caption, message box, status bar, and tooltips.
Row HeightWhen the “r” (row) GUI option (Ex: gui Add, Text, r10) is used to determine the height of the text displayed in GUI controls that can display multiple lines of text (Button, Edit, Text, WebBrowser, etc.)
Tab Stop SizeThe content for this topic can be found here.
LinksFont and Text Reference
CreditSome of the code in this library and in the example scripts was extracted from the AutoHotkey source.
Functions
Fnt_AddFontFileAdd one or more fonts from a font file (Ex: “MySpecialFont.ttf”) to the system font table.
Fnt_CalculateSizeCalculate the width and height of text.
Fnt_ChooseFontCreates and shows a Font dialog box that enables the user to choose attributes for a logical font.
Fnt_CloneFontCreates a logical font with the same attributes as the specified logical font.
Fnt_Color2ColorNameConvert a color value into one of 16 color names if a match is found.
Fnt_Color2RGBConvert a color value to it’s 6-digit hexadecimal RGB value.
Fnt_ColorName2RGBConvert a color name to it’s 6-digit hexadecimal RGB value.
Fnt_CompactPathShortens a file path to fit within a given pixel width by replacing path components with ellipses.
Fnt_CreateFontCreates a logical font.
Fnt_CreateCaptionFontCreates a logical font with the same attributes as the caption font.
Fnt_CreateMenuFontCreates a logical font with the same attributes as the font used in menu bars.
Fnt_CreateMessageFontCreates a logical font with the same attributes as the font used in message boxes.
Fnt_CreatePitchAndFamilyFontCreate a font by pitch and font family rather than by font name.
Fnt_CreateSmCaptionFontCreates a logical font with the same attributes as the small caption font.
Fnt_CreateStatusFontCreates a logical font with the same attributes as the font used in status bars and tooltips.
Fnt_CreateTooltipFontCreates a logical font with the same attributes as the font used in tooltips.
Fnt_DeleteFontDeletes a logical font.
Fnt_DialogTemplateUnits2PixelsConverts dialog template units to pixels for a font.
Fnt_EnumFontFamExProcThe default EnumFontFamiliesEx callback function for the Fnt library.
Fnt_FontExistsDetermines if a typeface exists on the current computer.
Fnt_FontSizeToFitDetermines the largest font size that can be used to fit a string within a specified width.
Fnt_FontSizeToFitDTDetermines the largest font size that can be used to fit a string within a specified width.
Fnt_FontSizeToFitHeightDetermines the largest font size that can be used to fit within a specified height.
Fnt_FODecrementSizeDecrements the value of the size option within a font options string.
Fnt_FOGetColorGet the color name or RGB color value from the color option within a font option string.
Fnt_FOGetQualityGet the value of the last Quality option within a font options string.
Fnt_FOGetSizeGet the size value of the last size option within a font options string.
Fnt_FOGetWeightGet the weight value of the last weight option within a font options string.
Fnt_FOIncrementSizeIncrements the value of the size option within a font options string.
Fnt_FORemoveColorRemoves all color options from a font options string.
Fnt_FORemoveQualityRemoves all quality options from a font options string.
Fnt_FORemoveWeightRemoves all “w”eight and “bold” options from a font options string.
Fnt_FOSetColorSets or replaces all color options within a font options string.
Fnt_FOSetQualitySets or replaces all quality options within a font options string.
Fnt_FOSetSizeSets or replaces all size options within a font options string.
Fnt_FOSetWeightSets or replaces all weight options within a font options string.
Fnt_GetAverageCharWidthCalculates the average width of characters in a font.
Fnt_GetCaptionFontNameReturns the font name of the caption font.
Fnt_GetCaptionFontOptionsReturns the font options of the caption font.
Fnt_GetCaptionFontSizeReturns the point size of the caption font.
Fnt_GetBoldGUIFontReturns the handle to a font that has the same attributes as the default GUI font but with a weight of 700, i.e.
Fnt_GetDefaultGUIFontReturns the handle to the default GUI font.
Fnt_GetDefaultGUIMarginsCalculates the default margins for an AutoHotkey GUI.
Fnt_GetDialogBackgroundColorRetrieves the current dialog background color.
Fnt_GetDialogBaseUnitsCalculates the dialog base units, which are the average width and height (in pixels) of characters of a font.
Fnt_GetListOfFontsGenerate a list of uniquely-named font names.
Fnt_GetLastTooltipGet the handle to last created tooltip control (if any).
Fnt_GetLongestStringDetermines the longest string (measured in pixels) from a list of strings.
Fnt_GetLongestStringDTDetermines the longest string (measured in pixels) from a list of strings.
Fnt_GetFontRetrieves the font with which a control is currently drawing its text.
Fnt_GetFontAvgCharWidthRetrieves the average width of characters in a font (generally defined as the width of the letter “x”).
Fnt_GetFontEmHeightRetrieves the em height of characters in a font.
Fnt_GetFontExternalLeadingRetrieves the amount of extra leading space (if any) that an application may add between rows.
Fnt_GetFontHeightRetrieves the cell height (ascent + descent) of characters in a font.
Fnt_GetFontInternalLeadingRetrieves the amount of leading space (if any) inside the bounds set by the tmHeight member.
Fnt_GetFontMaxCharWidthRetrieves the width of the widest character in a font.
Fnt_GetFontMetricsRetrieves the text metrics for a font.
Fnt_GetFontNameRetrieves the typeface name of the font.
Fnt_GetFontOptionsRetrieves the characteristics of a logical font for use in other library functions or by the AutoHotkey gui Font command.
Fnt_GetLogicalFontNameRetrieves the typeface name of the font.
Fnt_GetLogicalFontOptionsRetrieves the attributes of a logical font in the AutoHotkey “gui Font” format.
Fnt_GetFontQualityGet the font’s output quality.
Fnt_GetFontSizeRetrieves the point size of a font.
Fnt_GetFontWeightRetrieves the weight (thickness or boldness) of a font.
Fnt_GetMenuFontNameReturns the font name of the font used in menu bars.
Fnt_GetMenuFontSizeReturns the point size of the font that is used in menu bars.
Fnt_GetMenuFontOptionsReturns the font options of the font that is used in menu bars.
Fnt_GetMessageFontNameReturns the font name of the font that is used in message boxes.
Fnt_GetMessageFontOptionsReturns the font options of the font that is used in message boxes.
Fnt_GetMessageFontSizeReturns the point size of the font that is used in message boxes.
Fnt_GetMultilineStringSizeCalculates the size of a multiline string for a font.
Fnt_GetMultilineStringSizeDTCalculates the size of a multiline string for a font.
Fnt_GetNonClientMetricsRetrieves the metrics associated with the nonclient area of nonminimized windows.
Fnt_GetPosGet the position and size of a GUI control.
Fnt_GetSmCaptionFontNameReturns the font name of the small caption font.
Fnt_GetSmCaptionFontOptionsReturns the font options of the small caption font.
Fnt_GetSmCaptionFontSizeReturns the point size of the small caption font.
Fnt_GetStatusFontNameReturns the font name of the font used in status bars and tooltips.
Fnt_GetStatusFontOptionsReturns the font options of the font that is used in status bars and tooltips.
Fnt_GetStatusFontSizeReturns the point size of the font that is used in status bars and tooltips.
Fnt_GetTooltipFontNameReturns the font name of the font used in tooltips.
Fnt_GetTooltipFontOptionsReturns the font options of the font that is used in tooltips.
Fnt_GetTooltipFontSizeReturns the point size of the font that is used in tooltips.
Fnt_GetSizeCalculates the width and height of text that will used in a GUI control.
Fnt_GetSizeForButtonCalculates the width and height of text that will used in a button control.
Fnt_GetSizeForEditCalculates the width and height of text that will used in an Edit control.
Fnt_GetSizeForTextCalculates the width and height of text that will used in a static control like the Text control.
Fnt_GetSizeForTextNoPrefixCalculates the width and height of text that will used in a static control like the Text control.
Fnt_GetStringSizeCalculates the width and height (in pixels) of a string of text.
Fnt_GetStringSizeDTCalculates the width and height (in pixels) of a string of text.
Fnt_GetStringWidthCalculates the width (in pixels) of a string of text.
Fnt_GetStringWidthDTCalculates the width (in pixels) of a string of text.
Fnt_GetSysColorRetrieves the current color of the specified display element.
Fnt_GetTabbedStringSizeCalculates the width and height (in pixels) of a string of text.
Fnt_GetTotalRowHeightCalculates the height of a given number of rows of text for a font.
Fnt_GetWindowColorRetrieves the current window (background) color.
Fnt_GetWindowTextColorRetrieves the current window text color.
Fnt_HorzDTUs2PixelsConverts horizontal dialog template units to pixels for a font.
Fnt_IsFixedPitchFontDetermines if a font is a fixed pitch font.
Fnt_IsFontDetermines if the hFont parameter contains the handle to valid logical font.
Fnt_IsTrueTypeFontDetermines if a font is a TrueType font.
Fnt_Pixels2DialogTemplateUnitsConverts pixels to dialog template units for a font.
Fnt_RemoveFontFileRemove the font(s) added with Fnt_AddFontFile.
Fnt_RGB2ColorNameConvert a RGB value into one of 16 color names if a match is found.
Fnt_SetFontSets the font that the control is to use when drawing text.
Fnt_SetTooltipFontCreates a font and sets the last created tooltip control to use the font.
Fnt_String2DialogTemplateUnitsConverts a string to dialog template units for a font.
Fnt_String2DialogTemplateUnitsDTConverts a string to dialog template units for a font.
Fnt_TruncateStringToFitReturns a string, truncated if necessary, that is less than or equal to a specified maximum width, in pixels.
Fnt_TruncateStringWithEllipsisSimilar to Fnt_TruncateStringToFit except that if the string is truncated, the end of a string is replaced with an ellipses.
Fnt_TwipsPerPixelDetermines the number of twips (abbreviation of “twentieth of an inch point”) for every pixel on the screen.
Fnt_UpdateTooltipForces the tooltip to be redrawn.
Fnt_VertDTUs2PixelsConverts vertical dialog template units to pixels for a font.
Add-On FunctionsAdd-On functions are functions stored in separate library files.
Functions
Fnt_AutoFormatTabbedTextFormat tab-delimited text so the columns will align correctly when displayed.
Fnt_ChooseFontDlgAn alternative to the Fnt_ChooseFont function.
Fnt_ChooseFontDlg_ChooseColorCreates a Color dialog box that enables the user to select a color.
Fnt_ChooseFontDlg_SBSetTextSet the text in the specified part of a status bar.
Fnt_HardWordBreakInserts hard line breaks into a string of text so that the maximum width of each line is less than or equal to a specified width, in pixels.
Fnt_RandomFontGets a random font.
Fnt_RandomTTFontGets a random True Type font.
Fnt_RandomTTFPFontGets a random fixed pitch True Type font.
Fnt_RandomTTVPFontGets a random variable pitch True Type font.

Introduction

Fonts are logical objects that instruct the computer how to draw text on a device (display, printers, plotters, etc.).  This library provides a means of managing some of the aspects of fonts used in AutoHotkey.

AutoHotkey Compatibility

This library is designed to run on all recent versions of AutoHotkey v1.1+

ANSI, Unicode, and Unicode 64-bit.

Common Parameters

Common function parameters of note.

hFont

This input parameter should contain the handle to to a logical font.

hFont is the de facto first parameter for most of the library functions.  It is critical to the success of the library.  To avoid errors and to improve flexibility, many (but not all) of the library function will automatically collect the handle to the default GUI font (a stock font) if the hFont parameter is zero, null, or unspecified.

Terminology

Image courtesy of csharphelper.com.  Used with permission.

Font terminology is not always intuitive and is often ambigious.  The following are a few of the terms that may be used in this library.

AscentThe part of the character cell above the baseline.  This includes the internal leading.  Also known as “ascender”.
BaselineAn imaginary line on which the majority of the characters in a font rest.
Bitmap FontA type of font that stores each character as an array of pixels, i.e. a bitmap.  It is less commonly known as a raster font.
Cell HeightSee the Height definition for more information.
Character CellAn imaginary box that surrounds the individual character.  It includes the ascent (which includes the internal leading) and the decent.
DescentThe part of the character cell below the baseline.  Also known as “descender”.
Device FontHardware fonts created for a specific device (Ex: printer).
Em HeightThe height within which the characters are drawn.  This is the cell height less the internal leading.  This is sometimes known as the “character height” or “text height”.  The font’s point size is calculated based on the em height.  Use Fnt_GetFontEmHeight to get the font’s em height.
External LeadingWhen multiple lines of text are displayed, external leading is extra space left below one line and above the next.  This value may be zero.  Use Fnt_GetFontExternalLeading to get the font’s external leading.  Note: External leading is not a part of the character cell.  It is up to the developer/OS to determine if it is used or not.  Most (all?)  GUI controls do not use external leading to space multiple lines of text.
Font FamilySee the Font Family and Font Family[Secondary Definition] topics for more information.
Font MappingThe process of finding the physical font that most closely matches a specified logical font.  In addition, the font mapping algorithm is used to establish the necessary values of the font when the logical font is created.  This allows the developer to create a font with little or no pertinent information.
HeightThe height (ascent (includes internal leading) + descent) of the font characters.  Also known as cell height.  Use Fnt_GetFontHeight to get the font’s height.
Internal LeadingExtra space left above the characters but considered part of the text.  This value may be zero.  Use Fnt_GetFontInternalLeading to get the font’s internal leading.
ItalicA (mostly) slanted font style.
KerningThe process of adjusting the spacing between characters in a proportional font, usually to create a visually pleasing result.  More information can be found here.
Logical FontAn object that contains a description of a font.  Logical fonts are created by the “CreateFont” or “CreateFontIndirect” API functions.  In the Fnt library, this task is accomplished by library functions with names that begin with “Fnt_Create”.  For example, Fnt_CreateFont.
Monospaced FontA font whose letters and characters each occupy the same amount of horizontal space.  Also called a fixed-pitch, fixed-width, or non-proportional font.
Outline FontA type of font that uses BĂ©zier curves, drawing instructions, and algorithms to describe each character, which make the character outlines scalable to any size.  Outline fonts are also called vector fonts.  Not to be confused with fonts that only draw the outline of each character.
Physical FontThe fonts stored on a device (Ex: printer) or in the operating system.
PitchFor fonts (and this library), the term “pitch” is used to identify whether the width of each letter/character is fixed (i.e. fixed-pitch or monospaced) or is variable (i.e. variable-pitch or proportional).
Point SizeThe traditional way font size is measured.  Each point represents approximately 1/72 of an inch.  Fonts created using the AutoHotkey “gui Font” command are created in point size.  Also, the size selected in the ChooseFont dialog is in point size.  See the Em Height definition for more information.
Proportional FontA font whose letters and characters each occupy a different amount of horizontal space.  Also called a variable-pitch or proportional-pitch font.
Raster FontSee the Bitmap Font definition for more information.
ScalableA type of font that can be resized (enlarged or reduced) without introducing distortion.  Scalable fonts are often called outline fonts.  See the Outline Font definition for more information.  Note: All TrueType fonts are outline fonts and therefore are scalable but not all scalable fonts are TrueType fonts.
StrikeoutA font style that causes text to appear as though it is crossed out.  Also known as “strikethrough”.
TrueTypeAn outline font standard developed by Apple and Microsoft as a competitor to Adobe’s Type 1 fonts used in PostScript.  It is the most common format for fonts on the macOS and Microsoft Windows operating systems.
TypefaceA particular design of type.  For example, Arial, Garamond, and Times New Roman are all unique typefaces.
Vector FontSee the Outline Font definition for more information.
UnderlineA font style that causes text to appear as though it is underlined.
WeightThe thickness or boldness of a font.

Issues and Considerations

Differences from AutoHotkey

This library attempts to emulate AutoHotkey behavior when possible but there are a few notable exceptions.

Font Name Not Specified Or Not Found

When creating a font, AutoHotkey and the Fnt library operate the same in most cases but there are notable exceptions.

If the font name and font options are not specified, AutoHotkey and the Fnt library operate the same.  In both cases, the default GUI font is used.

If the font name is not specified but one or more font options are specified, Autohotkey uses the last valid font name that was defined, if any.  If no previous font was specified, the font name of the default GUI font is used.  For the Fnt library, the font name of the default GUI font is used in this situation.

If a typeface that does not exist on the current computer is specified (Ex : “BobIsYourUncle Light”), AutoHotkey will use the font name of the previously defined font or the font name of the default GUI font if no previous font was defined.  If this condition occurs when using the Fnt library, the font mapping algorithm chooses a font name based upon the default pitch and font family.  For most computers, the default typeface is “Arial” but it could be anything.  The value of font options (Ex: size, bold, etc.) can factor into which typeface is selected.

Retained Font Attributes

In AutoHotkey, the font name and/or font attributes (Ex: bold, underline, etc.) are retained from the previous “gui font” command(s).  They are only reset when a “gui font” command is performed without any other command options.  The Fnt library does not support this behavior.  All fonts are created independent of any other fonts.

Text Color

In AutoHotkey, color is one of the possible font option when creating/setting a font (Ex: “gui Font,s12 cBlue”).  When applicable, the specified color is applied to the text of a GUI control.  Although text color is an attribute of many common GUI controls, it is not a font attribute and therefore it is not a supported font option when creating a font using the Fnt library.  If specified, the color option is ignored.  However, the color option is a recognized font option and is supported by several standard and helper Fnt library functions.  Please note that there are no Fnt library functions at this writing that apply a color to a GUI control.  If needed, this action must be performed outside of this library.

DPI-Aware

The functions in this library are not DPI-aware.  Specified position and size values are used as-is and the values returned from library functions are not adjusted to reflect a non-standard screen DPI.

Starting with AutoHotkey v1.1.11, a DPIScale option was added for AutoHotkey GUIs which makes most “gui” commands DPI-aware.  Although the AutoHotkey “gui” commands will not interfere with with any of the library commands (and vice versa), the size and position used by each may be incompatible when used on a computer that is using a non-standard DPI.  The DPIScale feature is enabled by default so if necessary, it must be explicitly disabled for each GUI.  Ex: gui -DPIScale.

Font Family

Definition

For fonts used in Windows, a font family is the font or group of fonts that represent a particular typeface.  For example, the “Verdana” font family contains the following fonts:

Verdana
Verdana Bold
Verdana Bold Italic
Verdana Italic

Notice that the fonts in this font family are for different styles or combination of styles but they are all for the same typeface, i.e. Verdana.

Typeface vs.  Font Family

For many fonts, the terms “typeface” and “font family” can be used interchangeably.  For example, the only font family available for the Verdana typeface is “Verdana”.  However, some typeface are represented by multiple font families.  For example, the Arial typeface is represented by two font families - “Arial” and “Arial Black”.

Multiple font families per typeface is a necessary evil because of how fonts are designed to work in Windows.  From a positive perspective, it allows font developers the ability to 1) make changes to existing fonts and to 2) introduce new font families without breaking existing programs.

Considerations

When creating a font using native AutoHotkey commands or the “CreateFont” functions in this library, the the correct font family must be specified.  For example, the font mapping algorithm will never find the “Arial Black” font family no matter what font attributes are specified if the “Arial” font family is specified.

Although it is perfectly acceptable for the developer to specify the font’s full name when creating a font (Ex: “Arial Bold Italic”), it’s better practice to specify the font family (i.e.  “Arial”) with the desired font options (i.e. bold, italic, etc.) and let the font mapping algorithm determine the font that is used.

It should be noted that some programs (especially native Windows programs) try hard to combine like font families into a single group.  For example, the Font window in the Control Panel and the ChooseFont API (used by Fnt_ChooseFont) combine like font families into a single group.  This works OK for some typefaces like Arial but doesn’t work as well for typefaces like Segoe which are represented by a large number of font families.

Font Family [Secondary Definition]

Definition

Font families describe the look of a font in a general way.  They are intended for specifying fonts when the exact typeface desired is not available.  The values for font families are as follows.

FF_DONTCARE (0x0)No font family.
FF_ROMAN (0x1)Proportional fonts with serifs.  Ex: Times New Roman.
FF_SWISS (0x2)Proportional fonts without serifs.  Ex: Arial.
FF_MODERN (0x3)Monospaced fonts, with or without serifs.  Ex: Courier New.
FF_SCRIPT (0x4)Fonts designed to look like handwriting.  Ex: Script.
FF_DECORATIVE (0x5)Novelty fonts.

Issues and Considerations

Most fonts are categorized correctly but there are a few notable exceptions.  The following are observations of the fonts on my computer but these issues probably occur on most computers.

1) A few fonts may be categorized incorrectly.  For example, a font may be categorized as Modern (i.e. a monospaced font) but the font may be a proportional font.

2) A notable number of fonts are not categorized, i.e. the font family is set to FF_DONTCARE.  The font’s designer sets the font family so the decision to set the font family to FF_DONTCARE may be arbitrary.  The “Don’t Care” constant name probably doesn’t help.

Font Height

Starting with v3.0, a font created using the Fnt library can be created with a specific height.  In many cases, fonts created with a specified height do not have an exact point size equivalent.  This means that the font cannot be duplicated using AutoHotkey commands.  See the Font Height section of Fnt_CreateFont for more information.

Global Variables

This library uses a few global variables.  They are as follows.

Fnt_EnumFontFamExProc_List[Input/Output] Used by Fnt_EnumFontFamExProc to build a list of unique font names.  Fnt_GetListOfFonts returns the list of fonts stored in this global variable to any program that calls the function.

Measuring Text Size

Introduction

Version 3.0 of the library introduces changes to how text can be measured.  Library functions that use the “GetTextExtentPoint32” API function to measure text have not been modified (except where noted).  Ex: Fnt_GetStringSize.  New versions of these library functions that use the “DrawText” API function to measure text have been created for v3.0.  The new function names are the same as as old except “DT” is appended to the end of the name.  Ex: Fnt_GetStringSizeDT.

What’s The Difference?

In general, the library functions that use the “DrawText” API function return a more accurate and consistent result than the functions that use the “GetTextExtentPoint32” API function.

For width, the measurement differences of “GetTextExtentPoint32” function as compared to the “DrawText” function vary from font to font and from the text is measured.  The measurements from the two functions are often the same.  If there is a measurement difference, it is often just a few pixels.  On occasion, depending on the font and the text, the differences can be significant.

With a bug fix introduced in v3.0, the height measurements are the same.

Other Differences

By default, the “GetTextExtentPoint32” API function does not consider carriage return and line feed characters characters when it computes the height of a text string.  In addition, tab characters are not expanded.  However, if these characters are included in the text, they are treated as ordinary characters and are measured.

For the “DrawText” API function, carriage return and line feed characters are treated as ordinary characters if the DT_SINGLELINE format is specified.  If the DT_EXPANDTABS format is not specified, tab characters are treated as ordinary characters.

The measurements from the “GetTextExtentPoint32” function for these characters can be (and usually are) different than the measurements from “DrawText” function.  Sometimes the differences are significant.

Performance

The “DrawText” API function is significantly less efficient than “GetTextExtentPoint32” API function.  For most fonts and for the average amount of text that is measured, the response difference is negligible.  However, for some fonts and when a large amount of text is measured, the time to measure the text can be substantial and so consideration and planning are a must.  Note: The resources to measure the text are used by the “DrawText” API function and so increasing the priority of the script does not improve response in these cases.

When To Use

The library functions that use the “GetTextExtentPoint32” API function should be used when the results of the measurement are not critical and/or when a large number of strings are measured.  Since they are more efficent that the library functions that use the “DrawText” API function (sometimes significantly), they should be used whenever possible.

The library functions that use the “DrawText” API function should be used when the results of the measurement are critical.  For example, when measuring text to see if it fits within a tab stop, the functions that use the “DrawText” API function return the most accurate results.

Most of the common/default fonts work fine when the “GetTextExtentPoint32” API function is used to measure the text.  Testing should give the developer the necessary information to determine which functions should be used on a case by case basis.  If the user is allowed to select the font that is used, more thorough testing is merited.

New Functions

Version 3.0 also includes entirely new functions that use the “DrawText” API function to measure text.  Fnt_CalculateSize is the most flexible but there are new functions designed specifically for certain GUI controls (Ex: Fnt_GetSizeForButton.  The “DrawText” function is used because if provides new options to help accurately determine the size of text that will be used for certain GUI controls.  Because of the additional resources required by the “DrawText” API function, consideration and planning are a must.

Non-Client Fonts

Non-Client (sometimes written as “nonclient”) fonts are the fonts used by the caption (text on the title bar), small caption, message box, status bar, and tooltips.  These fonts are set by default when the user selects a theme and text size (DPI).  These settings can be customized by the user by going to the Advanced Appearance Settings in the Control Panel.  These font setting are rarely changed by an application.  The exceptions are the fonts for tooltips and the status bar.

Tooltip

Although the tooltip font is rarely changed, it can be changed by the developer to reflect the needs of the application.  This library includes a fairly reliable method to find the handle of the last tooltip created.

Status Bar

When a status bar is added to an AutoHotkey GUI, AutoHotkey will use whatever font was last set or the default GUI font if nothing else was set.  This means that font used by the status bar is never set to the appropriate non-client font unless the developer explicitly sets it.  See the example scripts to see how to use the Fnt library to set the font for the status bar to the appropriate non-client font.

Row Height

When the “r” (row) GUI option (Ex: gui Add, Text, r10) is used to determine the height of the text displayed in GUI controls that can display multiple lines of text (Button, Edit, Text, WebBrowser, etc.), AutoHotkey calculates the height by adding up the font height for each row, including the space between each row (external leading) if there is more than one row.  This calculation is incorrect because GUI controls don’t use the font’s external leading value to separate lines of text.  The calculation error is off by the external leading value for the font times the number of lines minus 1, i.e. ExternalLeading*(NbrOfLines-1).  For example, if the external leading value for a font is 2 and the number of rows is 10, the calculation will be off (too tall) by 18 pixels (2 pixels * (10 rows - 1)).  This calculation error doesn’t present itself often because many fonts have a zero (0) external leading value.

The workaround is to calculate the row height manually.  Multiplying the font’s height by the desired number of rows (Ex: Fnt_GetFontHeight(hFont)*9) is a good start.  This calculation works fine as-is for a few GUI controls (Ex: Text and WebBrowser), however, for many other controls that display multiple lines of text (Ex: Edit control) a fixed amount of space (usually 8 pixels) must be added to the height to give it the correct height.  In addition, space for other controls (Ex: horizontal scroll bar) must be included if needed.  See the example scripts for more examples.

Tab Stop Size

The content for this topic can be found here.

Credit

Some of the code in this library and in the example scripts was extracted from the AutoHotkey source.  Thanks to authors of AutoHotkey.

The Fnt_ChooseFont function was originally adapted from the Dlg library which was published by majkinetor.

The Fnt_GetListOfFonts function was inspired by an example published by Sean.

Functions

Fnt_AddFontFile

Fnt_AddFontFile(p_File,  
p_Private,  
p_Hidden: = False)

Description

Add one or more fonts from a font file (Ex: “MySpecialFont.ttf”) to the system font table.

Parameters

p_FileThe full path and name of the font file.
p_PrivateIf set to TRUE, only the process that called this function can use the added font(s).
p_HiddenIf set to TRUE, the added font(s) cannot be enumerated, i.e. not included when any program requests a list of fonts from the OS.  The default is FALSE, i.e. not hidden.

Returns

The number of the fonts added if successful, otherwise FALSE.

Remarks

All fonts added using this function are temporary.  If the p_Private parameter is set to TRUE, the added font(s) are automatically removed when the process that added the font(s) ends.  If p_Private is FALSE, the font(s) are only available for the current session.  When the system restarts, the font(s) will not be present.  If desired, use Fnt_RemoveFontFile to remove the font(s) added by this function.

A complete list of the font file types that can be loaded as well as additional considerations can be found here.

Fnt_CalculateSize

Fnt_CalculateSize( hFont,  
ByRef r_Text,  
 p_Options,  
ByRef r_Width: = "",
ByRef r_Height: = "")

Description

Calculate the width and height of text.  See the Remarks section for more information.

Parameters

hFontHandle to a logical font.  Set to null or 0 to use the default GUI font.
r_Text[Input/Output] A variable that contains the text used to determine the size of the rectangle.  See the End-Of-Line Character(s) section for more information.  If the p_Options parameter contains options to modify the text, this variable will be updated to contain the modified text.
p_OptionsOptions used to determine how the DrawTextEx function is used.  [Optional] See the Options section for more information.
r_Width, r_Height[Output, Optional] These variables are loaded with the calculated width and height of the rectangle.

Returns

The address to a SIZE structure.  The cx member contains the maximum width of the text.  The cy member contains the height of the text.

Maximum Width

The Width option (p_Options parameter) is used to set the maximum width of rectangle, in pixels.

If the Width option and WordBreak format is set, lines are automatically broken between words if a word extends past the maximum width.  Also, lines are broken into multiple lines if the text contains end-of-line (EOL) sequences (LF or CR+LF).

If the Width option is not set but the WordBreak format is set, the width of the rectangle is entirely determined by the text contained in the r_Text parameter.  Lines are only broken into multiple lines if the text contains EOL characters.

Options

The following options and DrawTextEx formats can be used in the p_Options parameter.

Bottom[Format] Justifies the text to the bottom of the rectangle.  This format is used only with the SingleLine format.
Center[Format] Centers text horizontally in the rectangle.
CalcRect[Format] Determines the width and height of the rectangle but does not draw the text.  Note: This option is for reference only.  This format is included by default.
EditControl[Format] Duplicates the text-displaying characteristics of a multiline edit control.  Specifically, the average character width is calculated in the same manner as for an Edit control, and the function does not display a partially visible last line.
End_Ellipsis[Format] For displayed text, replaces the end of a string with ellipses so that the result fits in the specified rectangle.  Any word (not at the end of the string) that goes beyond the limits of the rectangle is truncated without ellipses.  The text is not modified unless the ModifyString option is specified.  Compare with the Path_Ellipsis and Word_Ellipsis options.
ExpandTabs[Format] Expands tab characters.  The default number of characters per tab is 8.
ExternalLeading[Format] Includes the font external leading in line height.  Normally, external leading is not included in the height of a line of text.
Format={Format}Sets the DrawTextEx format as an integer value.  Ex: Format=0x18D40.  Note: This option will override any format value(s) that may have been previously defined.  If other format options follow this option, their values are added to this value.
HidePrefix[Format] Ignores the ampersand (&) prefix character in the text.  The letter that follows will not be underlined, but other mnemonic-prefix characters are still processed.  Compare with the NoPrefix and PrefixOnly formats.  See the full documentation on the DT_HIDEPREFIX flag for examples.
Internal[Format] Uses the system font to calculate text metrics.
Left[Format] Aligns text to the left.  This format is for reference only.  Text is automatically left-justified unless there is an overriding format (Ex: Right).
LeftMargin={LeftMargin}The left margin, in pixels.  Ex: LeftMargin=12.  If this option is not specified, the left margin is set to 0.  Note: The Microsoft documentation incorrectly states that the left margin should be in units equal to the average character width.
ModifyString[Format] Modifies the text in the r_Text variable to match the displayed text.  This format has no effect unless the End_Ellipsis, Path_Ellipsis, or Word_Ellipsis formats are specified.
NoClip[Format] Draws without clipping.  The DrawTextEx function is somewhat faster when this format is used.
NoFullWidthCharBreak[Format] Prevents a line break at a DBCS (double-wide character string), so that the line-breaking rule is equivalent to SBCS strings.  For example, this can be used in Korean windows, for more readability of icon labels.  This format has no effect unless WordBreak format is specified.
NoPrefix[Format] Turns off processing of prefix characters.  Normally, the DrawTextEx function interprets the ampersand (&) mnemonic-prefix character as a directive to underscore the character that follows, and the double-ampersand (&&) mnemonic-prefix characters as a directive to print a single ampersand.  By specifying this format, this processing is turned off.  Compare with HidePrefix and PrefixOnly formats.
Path_Ellipsis[Format] For displayed text, replaces characters in the middle of the string with ellipses so that the result fits in the specified rectangle.  If the string contains backslash (\) characters, this format preserves as much as possible of the text after the last backslash.  The text is not modified unless the ModifyString option is specified.  Compare with the End_Ellipsis and Word_Ellipsis options.
PrefixOnly[Format] Draws only an underline at the position of the character following the ampersand (&) prefix character.  Does not draw any character in the string.  Compare with the NoPrefix and HidePrefix formats.  See the full documentation for the DT_PREFIXONLY format for examples.
Right[Format] Aligns text to the right.
RightMargin={RightMargin}The right margin, in pixels.  Ex: RightMargin=8.  If this option is not specified, the right margin is set to 0.  Note: The Microsoft documentation incorrectly states that the right margin should be in units equal to the average character width.
RTLReading[Format] Layout in right-to-left reading order for bidirectional text when the using is a Hebrew or Arabic font.  The default reading order for all text is left-to-right.
SingleLine[Format] Displays text on a single line only.  Carriage returns and line feeds do not break the line.
TabStop[Format] Sets tab stops.  This format is used in conjunction with the ExpandTabs format and the TabLength option.  If the TabLength option is not specified or is set to 0, the default tab length (8 average characters) is used.
TabLength={TabLength}The size of each tab stop, in units equal to the average character width.  Ex: TabLength=8.  This option is used in conjunction with the ExpandTabs and TabStop formats.  If either of these formats are not set, this option is ignored.  If this option is not specified, the default tab length (8) is used.
Top[Format] Justifies the text to the top of the rectangle.  This format is for reference only.  Text is automatically top-justified unless there is an overriding format (Ex: Bottom).
VCenter[Format] Centers text vertically.  This value is used only with the SingleLine format.
Width={WidthInPixels}The width of the rectangle in pixels.  Ex: Width=450.  See the Maximum Width section for more information.  Note: The value returned in the r_Width variable represents the calculated width of the rectangle which can be significantly different than this value.
WordBreak[Format] Breaks words.  Lines are automatically broken between words if a word extends past the edge of the rectangle.  A carriage return-line feed sequence also breaks the line.  Note: This format does not modify the text.  It is used to calculate the height of of the rectangle.
Word_Ellipsis[Format] Truncates any word that does not fit in the rectangle and adds ellipses.  Compare with the End_Ellipsis and Path_Ellipsis formats.

A few notes...

Options are processed in the order they are are defined, i.e. from left to right.  To use more than one option/format, include a space between each each.  For example: “NoClip ExpandTabs Width=500”

Average Character

For the “DrawTextEx” API function, an “average character” is a font-specific value.  How it is calculated depends on whether or not the DT_EDITCONTROL format is used.

If the DT_EDITCONTROL format is not used, an “average character” is the average width of characters in a font which is generally defined as the width of the letter x.  This value is collected directly from the font’s text metrics.  See Fnt_GetFontAvgCharWidth for more information.

If the DT_EDITCONTROL format is used, an average character is the equivalent of 1 dialog base unit.  This is the average size of a specific string of characters.  See Fnt_GetDialogBaseUnits for more information.

The “average character” size is only important when setting or calculating the tab stop size.  When calculating the tab stop size based upon a custom tab stop size, the DT_TABSTOP and DT_EXPANDTABS formats must be used.  If just calculating the default tab stop size, only the DT_EXPANDTABS format is necessary.

Tab Stop Size

When defining a custom tab stop size, the “DrawTextEx” function only supports a single tab stop size which means that all tab stops must be the same size.  For example, if the TabLength option (p_Options parameter) is set to 10, the first tab stop position is 10 average characters, the second is 20 average characters, and so on.  If the GUI control does not use a single custom tab stop size, the returned text size will not be accurate.

The “DrawTextEx” function only supports tab stops in increments of “average characters”.  This increment size is 4 times larger than what is supported by GUI controls that support a custom tab stop size.  If the actual tab stop size is not equal to an exact factor of an average character, the returned text size will not be accurate.  For example, tab stops for the Edit control are measured in “dialog template units” (DTUs).  There are 4 DTUs per “dialog base unit” (DBUs).  A DBU is the same as an “average character”.  A tab stop of 32 DTUs can be converted to exactly 8 “average characters” (32 DTUs/4 = 8 DBUs = 8 “average characters”).  However, if the tab stop on the Edit control is 30 DBUs, the conversion is 7.5 “average characters”.  Only integer values are supported so any conversion to “average characters” (i.e.  7 or 8) would be value that does not match the actual tab stop size so the returned text size will not be accurate.

Remarks

This function uses the “DrawTextEx” function to calculate the width and height of the specified text.  It is powerful and flexible but the correct options and format must be specified in order for accurate results to be returned.  Experimenting and testing are required in many cases.  See the example scripts for examples.

A few of the format options provide no value because they do not affect the size calculation but they remain for completeness.

Fnt_ChooseFont

Fnt_ChooseFont( hOwner: = 0,
ByRef r_Name: = "",
ByRef r_Options: = "",
 p_Effects: = True,
 p_Flags: = 0)

Description

Creates and shows a Font dialog box that enables the user to choose attributes for a logical font.

Parameters

hOwnerA handle to the window that owns the dialog box.  This parameter can be any valid window handle or it can be set to 0 or null if the dialog box has no owner.
r_NameFont name.  [Input/Output] On input, this variable can contain the default font name.  On output, this variable will contain the selected font name.
r_OptionsFont options.  [Input/Output] See the Options section for the details.
p_EffectsIf set to TRUE (the default), the dialog box will display the controls that allow the user to specify strikeout, underline, and text color options.
p_Flags[Advanced Feature] Additional ChooseFont flags.  [Optional] The default is 0 (no additional flags).  See the Flags section for more information.

Returns

TRUE if a font was selected, otherwise FALSE if the dialog was canceled or if an error occurred.

Calls To Other Functions

Flags

Flexibility in the operation of the Font dialog box is available via a large number of ChooseFont flags.  For this function, the flags are determined by constants, options in the r_Options parameter, and the value of the p_Effects parameter.  Although the flags set by these conditions will handle the needs of the majority of developers, there are a few ChooseFont flags that could provide additional value.  The p_Flags parameter is used to add additional ChooseFont flags to control the operation of the Font dialog box.  See the function’s static variables for a list of possible flag values.

This is an advanced feature.  Including invalid or conflicting flags may produce unexpected results.  Be sure to test throroughly.  With that said, many of the flags can be used to limit or exclude fonts.  This is a simple but powerful feature to only show the fonts that are needed for a particular task.

Options

On input, the r_Options parameter contains the default font options.  On output, r_Options will contain the selected font options.  The following space-delimited options (in alphabetical order) are available:

boldOn input, this option will preselect the “Bold” font style.  On output, this option is returned if a bold font was selected.
c{color}Text color.  {color} is one of 16 color names (see the AutoHotkey documentation for a list of supported color names) or a 6-digit hex RGB color value.  Example values: Blue or FF00FA.  On input, this option will attempt to pre-select the text color.  On output, this option is returned with the selected text color.  Notes and Exceptions: 1) The default text color is pre-selected if a color option is not specified or if the “Default” color is specified.  2) Color names (Ex: “Blue”) are only accepted on input.  A 6-digit hex RGB color value is set on output (Ex: 0000FF).  Exception: If the default text color is selected, the color name “Default” is set.  3) If p_Effects is FALSE, this option is ignored on input and is not returned.
h{HeightInPixels}[Input Only] Font height in pixels.  Ex: h20.  See the Height section for more information.
italicOn input, this option will preselect the “italic” font style.  On output, this option is returned if an italic font was selected.  Exception: If p_Effects is FALSE, this option is ignored on input and is not returned.
s{SizeInPoints}Font size in points.  For example: s12.  On input, this option will load the font size and if on the dialog’s “Size” list, will preselect the font size.  On output, the font size that was entered/selected is returned.
SizeMax{MaximumPointSize}[Input only] Sets the maximum point size the user can enter/select.  See the Size Limits section for more information.
SizeMin{MinimumPointSize}[Input only] Sets the minimum point size the user can enter/select.  See the Size Limits section for more information.
strikeOn input, this option will check the “Strikeout” option.  On output, this option is returned if the “Strikeout” option was checked.  Exception: If p_Effects is FALSE, this option is ignored on input and is not returned.
underlineOn input, this option will check the “Underline” option.  On output, this option is returned if the “Underline” option was checked.  Exception: If p_Effects is FALSE, this option is ignored on input and is not returned.
w{FontWeight}Font weight (thickness or boldness), which is an integer between 1 and 1000.  For example, 400 is Normal and 700 is Bold.  On input, this option will preselect the font style that most closely matches the weight specified.  If not specified, the default weight for the font is selected.  On output, this option is only returned if the weight is not Normal (400) and not Bold (700).

To specify more than one option, include a space between each.  For example: s12 cFF0000 bold.  On output, the selected options are defined in the same format.

Height

The “h{HeightInPixels}” option (p_Options parameter) allows the developer to specify a font size based on height instead of point size.  This option has the same precedence as the “s”ize option.  If both the “h” and “s” options are specified, the last one specified is used.

If the height value is positive (Ex: “h30”), the font mapping algorithm matches it against the cell height (ascent + descent) of the available fonts and will set/select the closest point size value.

If the height value is negative (Ex: “h-25”), the font mapping algorithm matches the absolute value against the em height (cell height less internal leading) of the available fonts and will set/select the closest point size value.

Note: This is an “input only” option.  The “h”eight option is not returned.  Instead, the function returns the point size selected.  Ex: “s16”.

Size Limits

By default, the font size is not tested.  The user can enter whatever they want in most cases.  The SizeMin and SizeMax options (r_Options parameter) change that by ensuring the size is between a certain range of values.  In addition, they also limit the sizes that are shown in the Size list box.

The SizeMin{MinimumPointSize} option sets the minimum point size the user can enter/select.  Ex: SizeMin10.  If this option is specified without also specifying the SizeMax option, the SizeMax value is automatically set to the maximum point size - 0xBFFF (49151).

The SizeMax{MaximumPointSize} option sets the the maximum point size the user can enter/select.  Ex: SizeMax72.  If this option is specified without also specifying the SizeMin option, the SizeMin value is automatically set to 0.

If the user enters a font size that is outside the boundaries set by the SizeMin and SizeMax options, a MsgBox dialog is shown and the user is not allowed to continue until a valid font size is entered/selected.

Note: If the SizeMin value is greater than the SizeMax value, both size limits are invalidated and no size limits are enforced.

Remarks

The ChooseFont dialog box supports the selection of text color.  Although text color is an attribute of many common controls, please note that it is not a font attribute.

Although the font weight can be any number between 1 and 1000, most fonts only support 2 weights.  For most fonts, the weights are 400 (Normal/Regular) and 700 (Bold).  A small number of fonts support other weights.  At this writing, the ChooseFont dialog does not display weight as a number.  Instead, weight is displayed as a font style like ExtraLight, Regular, Bold, Black, etc.  See the CreateFont documentation for a list of common font weight names and their associated values.

The ChooseFont dialog combines as many fonts into the fewest number of font names as possible.  For example, the “Arial” and “Arial Black” font families are combined into a single “Arial” font.  The “Arial Black” typeface is only returned when the “Arial” typeface is selected with the “Black” font style.  The merge algorithm works OK for most fonts but sometimes, some typeface and weight combinations cannot be selected.  For example, the “Segoe UI Semibold” font is available with weights of 600 and 800.  Only the font with the 600 weight can be selected.

The SizeMin and SizeMax options (r_Options parameter) not only affect the list of fonts sizes that are shown in the Font Size selection list box in the Font dialog box, they affect the font size that can be manually entered in the Font Size combo box.  If a font size that is outside the boundaries set by the SizeMin and SizeMax options, a MsgBox dialog is shown and the user is not allowed to continue until a valid font size is entered/selected.  Warning: If the value of the SizeMin option is greater than the SizeMax option, the “ChooseFont” API function will generate a CFERR_MAXLESSTHANMIN error and will return without showing the Font dialog box.

Programming Notes

Support for the CF_SHOWHELP flag was intentionally left out of this library because it would require the use of OnMessage commands.  The OnMessage command in turn would make any script that uses the Fnt library to be persistent.  Any script that included the Fnt library would need to use the ExitApp command to terminate the script.  If support for the CF_SHOWHELP flag is desired, use the Dlg_ChooseFont function in the Dlg2 library or use the Fnt_ChooseFontDlg add-on function.

Fnt_CloneFont

Fnt_CloneFont(hFont: = "")

Description

Creates a logical font with the same attributes as the specified logical font.

Returns

A handle to a logical font.

Credit

jeeswg

Remarks

When no longer needed, call Fnt_DeleteFont to delete the font.

Fnt_Color2ColorName

Fnt_Color2ColorName(p_Color,  
p_ConvertDefaultName: = False)

Description

Convert a color value into one of 16 color names if a match is found.

Type

Internal function.  Subject to change.  Do not use.

Parameters

p_ColorA color value in any format supported by the “c”olor option of the AutoHotkey “gui Font” command.  Example values: FF00FA, 0xABCDEF, Blue, Default
p_ConvertDefaultNameSee the Convert Default Name section for more information.

Returns

A color name (Ex: “Blue”) if a match is found, otherwise the original value is returned.

Calls To Other Functions

Convert Default Name

The p_ConvertDefaultName parameter allows the developer to determine what occurs if the “Default” color name is specified in the p_Color parameter.

If p_ConvertDefaultName is set to TRUE, the “Default” color value is converted to one of the 16 color names if a the default text color matches one of the 16 color names.  If no match is found, the original value (i.e.  “Default”) is returned.

If p_ConvertDefaultName is set to FALSE (the default), the original value (i.e.  “Default”) is returned in all cases.

Fnt_Color2RGB

Fnt_Color2RGB(p_Color)

Description

Convert a color value to it’s 6-digit hexadecimal RGB value.

Type

Internal function.  Subject to change.  Do not use.

Parameters

p_ColorA color value in any format supported by the “c”olor option of the AutoHotkey “gui Font” command.  Example values: FF00FA, 0xABCDEF, Blue, Default

Returns

A 6-digit hexadecimal RGB value.  Ex: 0xFF00FF.  If the function is unable to identify the color value, the value from Fnt_GetWindowTextColor is returned.

Calls To Other Functions

Remarks

This function should not be confused with Fnt_ColorName2RGB which only converts color names to RGB.

Fnt_ColorName2RGB

Fnt_ColorName2RGB(p_ColorName)

Description

Convert a color name to it’s 6-digit hexadecimal RGB value.

Type

Internal function.  Subject to change.  Do not use.

Parameters

p_ColorNameA color name (Ex: “Fuchsia”).  See the function’s static variables for a list of supported names.

Returns

A 6-digit hexadecimal RGB value.  Ex: 0xFF00FF.  If an invalid color name is specified or if the “Default” color name is specified, the value from Fnt_GetWindowTextColor is returned.

Calls To Other Functions

Fnt_CompactPath

Fnt_CompactPath(hFont,  
p_Path,  
p_MaxW,  
p_Strict: = False)

Description

Shortens a file path to fit within a given pixel width by replacing path components with ellipses.

Parameters

hFontHandle to a logical font.  Set to null or 0 to use the default GUI font.
p_PathA file path to shorten.  Ex: “C:\MyFiles\A long file name.txt”
p_MaxWThe maximum width for the return path, in pixels.
p_StrictIf set to TRUE, the function will return null if the minimum path value is longer (measured in pixels) than p_MaxW.  The default is FALSE.  See the Remarks section for more information.

Returns

The compacted path.

Calls To Other Functions

Remarks

By default, the path is not compacted beyond a minimum value which is usually a base file name preceded by ellipses.  If the value of p_MaxW is too small (relative to the specified font), the width of the minimum path value (measured in pixels) may be larger than p_MaxW.  If the p_Strict parameter is set to TRUE, the return value is set to null if the compacted path is wider than p_MaxW.  If p_Strict is set to FALSE (the default), the function will return whatever value is returned from the “PathCompactPath” function.

Fnt_CreateFont

Fnt_CreateFont(p_Name: = "",
p_Options: = "")

Description

Creates a logical font.

Parameters

p_NameFont name.  [Optional] If null or unspecified, the default GUI font name is used.
p_OptionsFont options.  [Optional] See the Options section for more information.

Options

The following options can be used in the p_Options parameter.

boldSet the font weight to the heaviest weight available.  The heaviest weight is 700 for most fonts but it can be higher for a few fonts.
h{HeightInPixels}Font height in pixels.  Ex: h20.  See the Font Height section for more information.
italicCreate an italic font.
normSets the font to normal weight/boldness and turns off italic, strike, and underline but the height/size is not modified.  See the Remarks section for more information.
q{Quality}Output quality.  Ex: q3.  See the function’s static variables for a list of possible quality values.
s{SizeInPoints}Font size in points.  Ex: s12.  See the Font Size section for more information.
-sRemove the “s”ize option.  See the Font Size and Remarks sections for more information.
strikeCreate a strikeout font.
underlineCreate an underlined font.
w{FontWeight}Font weight (thickness or boldness), which is an integer between 1 and 1000.  Ex: w600.  This option is usually unnecessary unless a specific weight is desired.  Use “bold” to select the font’s heaviest weight.

To specify more than one option, include a space between each.  For example: s12 bold

Returns

A handle to a logical font.

Calls To Other Functions

Font Height

The “h” option (p_Options parameter) allows the developer to create a font with a specific height.  This option has the same precedence as the “s”ize option.  If both the “h” and “s” options are specified, the last one defined is used.

If the height value is positive (Ex: “h30”), the font mapping algorithm matches it against the cell height (ascent + descent) of the available fonts.  Observation: For scalable fonts, the height of the new font is equal to or less than the requested height in most cases.

If the height value is negative (Ex: “h-25”), the font mapping algorithm matches the absolute value against the em height (cell height less internal leading) of the available fonts.

If the height value is zero (Ex: “h0”), the font mapping algorithm uses a default height value when searching for a match.

Important: Fonts created by height have a more precise size than fonts created using using the “s” (size) option.  Fonts created by height may not have an exact “s” (point size) equivalent.  To precisely duplicate a font created by height, use the same height value that was used to create the original font or use Fnt_CloneFont.

The “h” option is not available in AutoHotkey.  Like the “q” (quality) option, the “h” option is only available when creating a font.  This option is not returned when using Fnt_GetFontOptions.  After the font has been created, use Fnt_GetFontHeight to get the font’s height.

Font Size

The “s” option (p_Options parameter) allows the developer to create a font with a specific point size.  Ex: s12.

If the font size is zero (Ex: “s0”), the font mapping algorithm uses a default height value when searching for a match.  Note: This is same as setting the “h”eight value to zero (Ex: “h0”).

If a “s”ize, “-s”, or “h”eight option is not specified, the font size is set to the font size of the default GUI font.  This duplicates AutoHotkey behavior.  Observation: The point size of the default GUI font may be impractically small for the specified typeface.  Be sure to specify a point size if possible.  If unsure, try “s0”.

Remarks

When no longer needed, call Fnt_DeleteFont to delete the font.

If both the p_Name and p_Options parameters are null or unspecified, the handle to the default GUI font (a stock object) is returned.  This emulates the AutoHotkey behavior when no font has specified or when the “gui Font” command with no options is used.

The “norm” and “-s” font options (p_Options parameter) do not have any practical value for this function but they were included to be compatible with the AutoHotkey font options.  If used, they will generate the same results as if they were used in the “gui Font” command.

Fnt_CreateCaptionFont

Fnt_CreateCaptionFont()

Description

Creates a logical font with the same attributes as the caption font.

Returns

A handle to a logical font.

Calls To Other Functions

Remarks

When no longer needed, call Fnt_DeleteFont to delete the font.

Fnt_CreateMenuFont

Fnt_CreateMenuFont()

Description

Creates a logical font with the same attributes as the font used in menu bars.

Returns

A handle to a logical font.

Calls To Other Functions

Remarks

When no longer needed, call Fnt_DeleteFont to delete the font.

Fnt_CreateMessageFont

Fnt_CreateMessageFont()

Description

Creates a logical font with the same attributes as the font used in message boxes.

Returns

A handle to a logical font.

Calls To Other Functions

Remarks

When no longer needed, call Fnt_DeleteFont to delete the font.

Fnt_CreatePitchAndFamilyFont

Fnt_CreatePitchAndFamilyFont(p_Pitch: = 0,
p_Family: = 0,
p_Options: = "")

Description

Create a font by pitch and font family rather than by font name.

Type

Experimental/Preview.  Subject to change.

Parameters

p_PitchFont pitch.  The default is 0 which represents the default pitch.  See the function’s static variables for a list of possible font pitch values.  Alternatively, set to one of the following string values:
Value       Description
------      -----------
Default     Default pitch.
Fixed       Fixed-pitch (i.e. monospaced).
Variable    Variable-pitch (i.e. proportional).
p_FamilyFont family.  The default is 0 which represents an instruction to use the default font.  See the function’s static variables for a list of possible font family values.  Alternatively, set to one of the following string values:
Value       Description
------      -----------
Decorative  Novelty fonts.
DontCare    Use the default font.
Modern      Monospaced fonts, with or without serifs.  Ex: Courier New.
Roman       Proportional fonts with serifs.  Ex: Times New Roman.
Script      Fonts designed to look like handwriting.
Swiss       Proportional fonts without serifs.  Ex: Arial.
p_OptionsFont options.  [Optional] See the Options section of Fnt_CreateFont for more information.

Returns

A handle to a logical font.

Remarks

When no longer needed, call Fnt_DeleteFont to delete the font.

This function instructs the font mapping algorithm to choose from only TrueType fonts.  If there are no TrueType fonts installed in the system, the font mapping algorithm returns to default behavior.

Unlike Fnt_CreateFont, there is no condition where the handle to the default GUI font (a stock object) is returned.  In addition, there is no condition where the font size is set to the font size of the default GUI font.

Fnt_CreateSmCaptionFont

Fnt_CreateSmCaptionFont()

Description

Creates a logical font with the same attributes as the small caption font.

Returns

A handle to a logical font.

Calls To Other Functions

Remarks

When no longer needed, call Fnt_DeleteFont to delete the font.

Fnt_CreateStatusFont

Fnt_CreateStatusFont()

Description

Creates a logical font with the same attributes as the font used in status bars and tooltips.

Returns

A handle to a logical font.

Calls To Other Functions

Remarks

When no longer needed, call Fnt_DeleteFont to delete the font.

Fnt_CreateTooltipFont

Fnt_CreateTooltipFont()

Description

Creates a logical font with the same attributes as the font used in tooltips.

Returns

A handle to a logical font.

Calls To Other Functions

Remarks

When no longer needed, call Fnt_DeleteFont to delete the font.

This function is a clone of Fnt_CreateStatusFont.

Fnt_DeleteFont

Fnt_DeleteFont(hFont)

Description

Deletes a logical font.

Parameters

hFontHandle to a logical font.

Returns

TRUE if the font was successfully deleted or if no font was specified, otherwise FALSE.

Remarks

It is not necessary (but it is not harmful) to delete stock objects.

Fnt_DialogTemplateUnits2Pixels

Fnt_DialogTemplateUnits2Pixels( hFont,  
 p_HorzDTUs,  
 p_VertDTUs: = 0,
ByRef r_Width: = "",
ByRef r_Height: = "")

Description

Converts dialog template units to pixels for a font.

Parameters

hFontHandle to a logical font.  Set to null or 0 to use the default GUI font.
p_HorzDTUsHorizontal dialog template units.
p_VertDTUsVertical dialog template units.
r_Width, r_HeightOutput variables.  [Optional] These variables are loaded with the width and height conversions of the values from the p_HorzDTUs and p_VertDTUs parameters.

Returns

The address to a SIZE structure.

Calls To Other Functions

Fnt_EnumFontFamExProc

Fnt_EnumFontFamExProc(lpelfe,
lpntme,
FontType,
p_Flags)

Description

The default EnumFontFamiliesEx callback function for the Fnt library.

Type

Internal callback function.  Do not call directly.

Parameters

lpelfeA pointer to an LOGFONT structure that contains information about the logical attributes of the font.  To obtain additional information about the font, the result can be case as an ENUMLOGFONTEX or ENUMLOGFONTEXDV structure.
lpntmeA pointer to a structure that contains information about the physical attributes of a font.  The function uses the NEWTEXTMETRICEX structure for TrueType fonts; and the TEXTMETRIC structure for other fonts.  This can be an ENUMTEXTMETRIC structure.
FontTypeThe type of the font.  This parameter can be a combination of DEVICE_FONTTYPE, RASTER_FONTTYPE, or TRUETYPE_FONTTYPE.
p_Flags (i.e. lParam)The application-defined data passed by the EnumFontFamiliesEx function.

Returns

TRUE.

Remarks

This function uses a global variable (Fnt_EnumFontFamExProc_List) to build the list of font names.  Since this function is called many times for every request, the font name is always appended to this variable.  Be sure to set the Fnt_EnumFontFamExProc_List variable to null before every request.

Fnt_FontExists

Fnt_FontExists(p_Name*)

Description

Determines if a typeface exists on the current computer.

Type

Experimental/Preview.  Subject to change.

Parameters

p_Name*Zero or more parameters containing a font name (Ex: “Arial”), an AutoHotkey object with an array of font names (Ex: [“Calibri”,”Consolas”,”Courier”]), a comma-delimited list of font names (Ex: “Arial,Verdana,Helvetica”), or any combination of these types.  See the Remarks section for more information.

Returns

The first font name that exists from the p_Name parameter(s) (also tests as TRUE) if successful, otherwise null (also tests as FALSE).  See the Remarks section for more information.

Calls To Other Functions

Remarks

Although not case sensitive, the exact font name must be specified.

Leading and trailing white space, single quote, and double quote characters are ignored.  For example, “Arial,Segoe UI,Verdana” is the same as “Arial, ‘Segoe UI’, Verdana”

The font name is returned (i.e. success) if the font name is a valid font substitute.  Ex: “Helv”, “MS Shell Dlg”, “Times”, etc.

Programming Note

This function confirms the existence of a typeface by creating a temporary font and then collecting typeface name from the font and then comparing it to the specified name.  This method is used instead of font enumeration to avoid the rare but possible false positive that can occur when a typeface is only available for particular character set.

Fnt_FontSizeToFit

Fnt_FontSizeToFit(hFont,
p_String,
p_Width)

Description

Determines the largest font size that can be used to fit a string within a specified width.

Type

Experimental/Preview.  Subject to change.

Parameters

hFontHandle to a logical font.  Set to null or 0 to use the default GUI font.
p_StringAny string.  If this parameter is null, the current (or default) font size is returned.
p_WidthThe width to fit the string, in pixels.

Returns

The font size (in points) needed to fit the specified string within the specified size.

Calls To Other Functions

Remarks

This function uses a brute-force method to determine the font size needed.  The current font (from the hFont parameter) is checked first and then the size is incremented or decremented by one until the desired size is found.  Although this method is crude and can be resource intensive if there is large difference between the initial and final font size, it appears to be accurate for all fonts and all strings.  The function works the most efficiently if the developer starts with a font that is as close to desired size as possible.  If possible, this methodology will be improved in the future.

If the string cannot fit into the specified width, the smallest font size available is returned.  For scalable fonts, this size will always be 1.  For non-scalable fonts, the size will be whatever is the lowest font size is available.

This function identifies the point size of a font that is needed for a specified width.  However, the height of the font is not taken into consideration.  If the value returned by this function is used to set the font of a GUI control, the program may need to also set/correct the height of the control to avoid clipping or gaps.

The amount of space necessary to fit text within a fixed-size GUI control is usually a bit more than the size of the text itself.  Calculating the amount of dead/filler space required by the control for a specific font size is not too difficult.  However, identifying how must filler is needed when the font size is not known is a bit more difficult, if not impossible.  Artificially increasing the length of the string (p_String parameter) by one or more characters or artificially reducing the width (p_Width parameter) by a small amount will increase the accuracy (and usefulness) of the font size returned by this function if the value is used on a control that requires dead/filler space.  See the example script for an example of this technique.

The resources used by this function are very reasonable if the font size change is relatively small (<50 point size change).  However, if the change is large (>250 point size change) or very large (>500 point size change), the response time can range anywhere from noticeable to significant (>1 second).  If there is possibility of a large font size change in the script, performance can be significantly improved by setting SetBatchLines to a higher value before calling this function.  For example:

SetBatchLines 50ms
FontSize:=Fnt_FontSizeToFit(hFont,...)
SetBatchLines 10ms  ;-- This is the system default

Fnt_FontSizeToFitDT

Fnt_FontSizeToFitDT(hFont,
p_String,
p_Width)

Description

Determines the largest font size that can be used to fit a string within a specified width.

Type

Experimental/Preview.  Subject to change.

Remarks

This function is the same as Fnt_FontSizeToFit except that “DrawText” is used instead of “GetTextExtentPoint32” to measure the text size.  See Fnt_FontSizeToFit for more information.

Fnt_FontSizeToFitHeight

Fnt_FontSizeToFitHeight(hFont,
p_Height)

Description

Determines the largest font size that can be used to fit within a specified height.

Type

Experimental/Preview.  Subject to change.

Parameters

hFontHandle to a logical font.  Set to null or 0 to use the default GUI font.
p_HeightThe height, in pixels, to fit the font.

Returns

The font size (in points) needed to fit within the specified height.

Calls To Other Functions

Remarks

If a logical font cannot fit into the specified height, the smallest font size available is returned.  For scalable fonts, this size will always be 1.  For non-scalable fonts, the size will be whatever is the lowest font size is available.

Fnt_FODecrementSize

Fnt_FODecrementSize(ByRef r_FO,  
 p_DecrementValue: = 1,
 p_MinSize: = 1)

Description

Decrements the value of the size option within a font options string.

Type

Helper function.

Parameters

r_FOVariable that contains font options in the AutoHotkey format.
p_DecrementValueDecrement value.  The default is 1.
p_MinSizeThe minimize size.  The default is 1.

Returns

TRUE if successful, otherwise FALSE.  FALSE is returned if a “s”ize option is not defined or if decrementing the size would set the value below the p_MinSize value.

Calls To Other Functions

Fnt_FOGetColor

Fnt_FOGetColor(p_FO,  
p_DefaultColor: = "",
p_ColorName2RGB: = False)

Description

Get the color name or RGB color value from the color option within a font option string.

Type

Helper function.

Parameters

p_FOA string that contains font options in the AutoHotkey format.
p_DefaultColorThe value returned if no color option has been specified.  Set to a color name (see the AutoHotkey documentation for a list of supported color names), a 6-digit RGB value, the word “Default” to use the Windows default text color, or null (the default) to indicate no default color.  Example values: “Red”, “FF23AB”, “Default”.
p_ColorName2RGBIf set to TRUE and the color option (or p_DefaultColor if no color options are found) contains a valid color name (Ex: “Fuchsia”), the color name is converted to a 6-digit RGB Hex value (Ex: “FF00FF”).

Returns

The color specified by the last “c”olor option if found, otherwise the value specified in the p_DefaultColor parameter, if any.

Remarks

Since possible colors include 0x0 and “000000”, testing the return value for a TRUE/FALSE value will not always give the desired result.  Instead, check for a null/not null value or check the length of the return value.

Calls To Other Functions

Fnt_FOGetQuality

Fnt_FOGetQuality(p_FO,  
p_DefaultQuality: = 2)

Description

Get the value of the last Quality option within a font options string.

Type

Helper function.

Parameters

p_FOA string that contains font options in the AutoHotkey format.
p_DefaultQualityThe value returned if no “q”uality option has been specified.  The default is 2 (Proof) which is the AutoHotkey default.

Returns

The quality specified by the last “q”uality option if found, otherwise the value of the p_DefaultQuality parameter.

Remarks

If defined correctly, quality is an integer from 0 to 5.  See the static variables in Fnt_GetFontQuality for a list of valid values.  However, the value is stored in a single BYTE field and so any value from 0 to 255 can be returned.  If a value greater than 255 is specified, the number is truncated so that only the first byte of the value is returned.

Fnt_FOGetSize

Fnt_FOGetSize(p_FO,  
p_DefaultSize: = 0,
p_IgnoreZero: = True)

Description

Get the size value of the last size option within a font options string.

Type

Helper function.

Parameters

p_FOA string that contains font options in the AutoHotkey format.
p_DefaultSizeThe value returned if no size option has been specified.  The default is 0.
p_IgnoreZeroSee the Ignore Zero section for more information.

Returns

The size specified by the last “s”ize option if found and is not ignored, otherwise the value of the p_DefaultSize parameter.

Ignore Zero

Zero (0) is a possible value for the “s”ize option in a font option string.  Ex: “s0 bold italic”.  When used to create a font, a size of 0 will instruct the font mapping algorithm to use a default height value.  It’s not discussed in the AutoHotkey documentation so it’s use is tenuous at best.  A few developers may use it because they know or figured out what it does but most developers only specify a non-zero size.

The p_IgnoreZero parameter determines what happens if the p_FO parameter contains a “s”ize option with a zero (0) value.

If the p_IgnoreZero parameter is set to TRUE (the default), a “s”ize value of 0 is treated the same as if the p_FO parameter does not contain a “s”ize option at all.  This only affects the use of the p_DefaultSize parameter which is only used if the p_FO parameter does not contain a “s”ize option.

If the p_IgnoreZero parameter is set to FALSE, a “s”ize value of 0 is treated the same as any other size and will be returned as-is.  Note: Setting the p_IgnoreZero parameter to FALSE without also setting the p_DefaultSize to some non-zero value (Ex: -1) effectively does little because 0 is returned when a “s”ize value of 0 is set and when no “s”ize option is specified.

Please note that if the font option string contains more than one “s”ize option (Ex: “s12 bold s0”), only the last “s”ize option is used to determine the size of the font or if a valid/usable “s”ize option has been specified.

Fnt_FOGetWeight

Fnt_FOGetWeight(p_FO,  
p_DefaultWeight: = "")

Description

Get the weight value of the last weight option within a font options string.

Type

Helper function.

Parameters

p_FOA string that contains font options in the AutoHotkey format.
p_DefaultWeightThe value returned if no “w”eight or “bold” option has been specified.  The default is null.

Returns

The weight specified by the last “w”eight option if found or 700 if any “bold” option is found after any “w”eight options, otherwise the value of the p_DefaultWeight parameter.

Remarks

Since the weight value can be 0 (Ex: “w0”), testing the return value for a TRUE/FALSE value will not always give the desired result.  Instead, check for a null/not null value or check the length of the return value.

Fnt_FOIncrementSize

Fnt_FOIncrementSize(ByRef r_FO,  
 p_IncrementValue: = 1,
 p_MaxSize: = 999)

Description

Increments the value of the size option within a font options string.

Type

Helper function.

Parameters

r_FOVariable that contains font options in the AutoHotkey format.
p_IncrementValueIncrement value.  The default is 1.
p_MaxSizeThe maximum size.  The default is 999.

Returns

TRUE if successful, otherwise FALSE.  FALSE is returned if a “s”ize option is not defined or if incrementing the size would set the value above the p_MinSize value.

Calls To Other Functions

Fnt_FORemoveColor

Fnt_FORemoveColor(ByRef r_FO)

Description

Removes all color options from a font options string.

Type

Helper function.

Parameters

r_FOVariable that contains font options in the AutoHotkey format.

Returns

TRUE if at least one color option was removed, otherwise FALSE.

Fnt_FORemoveQuality

Fnt_FORemoveQuality(ByRef r_FO)

Description

Removes all quality options from a font options string.

Type

Helper function.

Parameters

r_FOVariable that contains font options in the AutoHotkey format.

Returns

TRUE if at least one quality option was removed, otherwise FALSE.

Fnt_FORemoveWeight

Fnt_FORemoveWeight(ByRef r_FO)

Description

Removes all “w”eight and “bold” options from a font options string.

Type

Helper function.

Parameters

r_FOVariable that contains font options in the AutoHotkey format.

Returns

TRUE if at least one “w”eight or “bold” option was removed, otherwise FALSE.

Fnt_FOSetColor

Fnt_FOSetColor(ByRef r_FO,
 p_Color)

Description

Sets or replaces all color options within a font options string.

Type

Helper function.

Parameters

r_FOVariable that contains font options in the AutoHotkey format.
p_ColorColor value.  This can be one of 16 color names (Ex: “Blue”), “Default” to indicate the system default text color, a 6-digit hexadecimal RGB color value (Ex: “FF00FA”), or a 6-digit hexadecimal RGB color number (Ex: 0xAABBCC).  See the AutoHotkey documentation for a list of supported color names

Calls To Other Functions

Fnt_FOSetQuality

Fnt_FOSetQuality(ByRef r_FO,
 p_Quality)

Description

Sets or replaces all quality options within a font options string.

Type

Helper function.

Parameters

r_FOVariable that contains font options in the AutoHotkey format.
p_QualityFont quality to set.

Calls To Other Functions

Remarks

No changes are made if p_Quality does not contain a positive integer value.

Fnt_FOSetSize

Fnt_FOSetSize(ByRef r_FO,
 p_Size)

Description

Sets or replaces all size options within a font options string.

Type

Helper function.

Parameters

r_FOVariable that contains font options in the AutoHotkey format.
p_SizeFont size to set.

Calls To Other Functions

Remarks

No changes are made if p_Size does not contain a positive integer value.

Fnt_FOSetWeight

Fnt_FOSetWeight(ByRef r_FO,
 p_Weight)

Description

Sets or replaces all weight options within a font options string.

Type

Helper function.

Parameters

r_FOVariable that contains font options in the AutoHotkey format.
p_WeightWeight to set.  Ex: 500.  This must be an integer between 0 and 1000.

Calls To Other Functions

Remarks

”bold” is considered a weight option (equivalent to “w700”) and is replaced if found.

Fnt_GetAverageCharWidth

Fnt_GetAverageCharWidth(hFont)

Description

Calculates the average width of characters in a font.

Parameters

hFontHandle to a logical font.  Set to null or 0 to use the default GUI font.

Returns

The average width of characters in the font, in pixels.

Calls To Other Functions

Remarks

This function should not be confused with Fnt_GetFontAvgCharWidth which returns the average character width as defined by the font’s designer which is usually the width of the letter “x”.  Although the results are similar, this function uses a Microsoft calculation which generates a consistent result regardless of the font.  Also note that this function returns the same value as the r_HorzDBUs output parameter of Fnt_GetDialogBaseUnits which contains the horizontal base units for the font.

The value returned by this function can be used to calculate the default tab stop size for several common controls (Edit, ListBox, RichEdit, others?).  For these controls, the default tab stop size is the font’s calculated average character width times 8.  Ex: Fnt_GetAverageCharWidth(hFont)*8.

Fnt_GetCaptionFontName

Fnt_GetCaptionFontName()

Description

Returns the font name of the caption font.

Calls To Other Functions

Remarks

This function gets the font name of the caption font without creating the font.

Fnt_GetCaptionFontOptions

Fnt_GetCaptionFontOptions()

Description

Returns the font options of the caption font.

Type

Helper function.

Calls To Other Functions

Remarks

This function converts the steps needed to collect the font options of the caption font into a single function call.

Fnt_GetCaptionFontSize

Fnt_GetCaptionFontSize()

Description

Returns the point size of the caption font.

Calls To Other Functions

Remarks

This function calculates the point size of the caption font without creating the font.

Fnt_GetBoldGUIFont

Fnt_GetBoldGUIFont()

Description

Returns the handle to a font that has the same attributes as the default GUI font but with a weight of 700, i.e. bold.

Type

Helper function.

Calls To Other Functions

Remarks

The font created by this function has the same attributes of the font created by AutoHotkey if the following command(s) are used:

gui Font       ;-- Only needed if a previous Font command was used
gui Font,Bold

This helper function creates and reuses a single logical font.  If the font is deleted (intentionally or otherwise), a new font is automatically created the next time the function is called.

Programming Note

This function depends on the Fnt_CreateFont function and the font that is created when default parameter values are specified.  If the default behavior of Fnt_CreateFont is modified, this function may need to be modified as well.

Fnt_GetDefaultGUIFont

Fnt_GetDefaultGUIFont()

Description

Returns the handle to the default GUI font.

Remarks

The default GUI font is a stock font.  It is created and maintained by the OS.  It is not necessary (but it is not harmful) to delete stock objects.

For many Fnt library functions, the default GUI font is automatically used if the hFont parameter is zero, null, or unspecified.

Fnt_GetDefaultGUIMargins

Fnt_GetDefaultGUIMargins( hFont: = "",
ByRef r_MarginX: = "",
ByRef r_MarginY: = "",
 p_DPIScale: = True)

Description

Calculates the default margins for an AutoHotkey GUI.

Parameters

hFontHandle to a logical font.  Set to null or 0 to use the default GUI font.
r_MarginX, r_MarginYOutput variables.  [Optional] These variables are loaded with the default margins (in pixels) for an AutoHotkey GUI.
p_DPIScaleFactor in the current display DPI into the default margin calculations.  Set to TRUE (the default) to enable or FALSE to disable.

Returns

The address to a POINT structure.

Calls To Other Functions

Remarks

AutoHotkey documentation for GUI margins...

Important: On rare occasion, the margins returned from this function may not match the actual GUI margins because the calculations are based on the actual font size of control, not the requested font size.  For example, if the developer uses the “gui Font” command to create a 24 point Courier (not “Courier New”) font, AutoHotkey will calculate margins based on this font/size.  However, when the font is actually created, the 24 point size is not available and so a Courier 15 point font is created instead.  So... the actual margins (based on the requested font/size) will not match the calculated margins (based on the actual font/size).  Hint: Stick to scalable fonts and this idiosyncrasy will never occur.

Starting with AutoHotkey v1.1.11, the formula to calculate the default GUI margins was changed to always factor in the current display DPI.  The “gui -DPIScale” command has no effect on this change.  The p_DPIScale parameter instructs the function whether or not to factor in the current display DPI.  If set to TRUE (the default), the current display DPI is factored into the calculation.  If set to FALSE, the default display DPI (96) is used.

Fnt_GetDialogBackgroundColor

Fnt_GetDialogBackgroundColor()

Description

Retrieves the current dialog background color.

Type

Internal function.  Subject to change.  Do not use.

Fnt_GetDialogBaseUnits

Fnt_GetDialogBaseUnits( hFont: = "",
ByRef r_HorzDBUs: = "",
ByRef r_VertDBUs: = "")

Description

Calculates the dialog base units, which are the average width and height (in pixels) of characters of a font.

Parameters

hFontHandle to a logical font.  Set to null or 0 to use the default GUI font.
r_HorzDBUs, r_VertDBUsOutput variables.  [Optional] These variables are loaded with the horizontal and vertical base units for the font.

Returns

The address to a SIZE structure.  The cx member of the SIZE structure contains the horizontal dialog base units for the font.  The cy member contains the vertical dialog base units.

Calls To Other Functions

Remarks

Unlike Fnt_GetFontAvgCharWidth which returns the average character width as defined by the font’s designer (usually the width of the letter “x”), this function uses a Microsoft calculation which generates an accurate and consistent result regardless of the font.

Fnt_GetListOfFonts

Fnt_GetListOfFonts(p_CharSet: = "",
p_Name: = "",
p_Flags: = 0)

Description

Generate a list of uniquely-named font names.

Parameters

p_CharSetCharacter set.  [Optional].  If blank/null (the default), the DEFAULT_CHARSET character set is used which will generate fonts from all character sets.  See the function’s static variables for a list of possible values for this parameter.
p_NameFont name.  [Optional] If blank/null (the default), one item for every unique font name is generated.  If set to a font name, that name is returned if valid.  Note: If specified, the font name must be exact (not case sensitive).  A partial name will return nothing.
p_FlagsFlags to filter the list of font names that are returned.  [Optional] See the Flags section for more information.

Returns

A list of uniquely-named font names that match the font characteristics specified by the parameters if successful, otherwise null.  Font names are delimited by the LF (Line Feed) character.

Calls To Other Functions

Flags

The p_Flags parameter is used to filter the list of font names that are returned.  This parameter can be a combination of any ChooseFont flag and a Font Family value.  See the function’s static variables for a list of possible flag values.  Note: Only one Font Family value can be specified per request.  The default is FF_DONTCARE.

Programming Notes

This function uses constants created for the ChooseFont dialog (constants that begin with “CF_”) and Font Family values (constants that begin with “FF_”) as possible values for the p_Flags parameter.  These constant names and values are from Microsoft.  In addition, custom constant names/values were created to support additional filter conditions.  The custom constant names begin with “CF_” for consistency but they are clearly marked as “custom”.

The Font Family values are stored in the first 4 bits (0 through 3) of the p_Flags parameter.  This only works because the Microsoft ChooseFont constants that fit into this bit range are not used to filter the list of font names.  Note that the Font Family constants contain a numeric value, not bit flag values.  Unlike the ChooseFont bit flag values that can can be combined, only one Font Family value can be specified per request.

Fnt_GetLastTooltip

Fnt_GetLastTooltip()

Description

Get the handle to last created tooltip control (if any).

Type

Helper function.

Returns

The handle to last created tooltip control (tests as TRUE) if successful, otherwise 0 (tests as FALSE).

Remarks

This function will return the handle to the last tooltip that was created.  If searching for the tooltip created by the AutoHotkey Tooltip command, this function should be called immediately after the tooltip has been created.  For example:

Tooltip Brown Chicken`, Brown Cow
hTT:=Fnt_GetLastTooltip()

After a tooltip control has been created, the same tooltip control is used even if the tooltip text is updated many times.  The tooltip control is only destroyed when the Tooltip command is called without specifying tooltip text.  For example:

Tooltip Brown Chicken                       ;-- New tooltip control is created
hTT:=Fnt_GetLastTooltip()                   ;-- The handle for the Tooltip control is collected
Sleep 2000
Tooltip Brown Cow
    ;-- New text, same tooltip control.
    ;   No need to get the handle to the
        tooltip control again.
Sleep 2000
Tooltip                                     ;-- The Tooltip control is destroyed

Fnt_GetLongestString

Fnt_GetLongestString(hFont,
p_String*)

Description

Determines the longest string (measured in pixels) from a list of strings.

Parameters

hFontHandle to a logical font.  Set to null or 0 to use the default GUI font.
p_String*Zero or more parameters containing a string, an array of strings, a list of strings delimited by end-of-line character(s) (see the *End-Of-Line Character(s)* section for more information), or any combination of these types.

Returns

The longest string found which can be null.  If more than one string is the same length as the longest string, the first one found is returned.  ErrorLevel is set to the length of the longest string (in pixels) which can be 0.

End-Of-Line Character(s)

Multiple strings can be represented as a single parameter value by inserting an end-of-line (EOL) delimiter between each string.  For example, “Label 1`nLongLabel 2`nLabel 3”.  The EOL character(s) in the string must be in a DOS/Windows (EOL=CR+LF), Unix (EOL=LF), or DOS/Unix mix format.  A multi-line string in any other format must be converted to a DOS/Windows or Unix format before calling this function.

Fnt_GetLongestStringDT

Fnt_GetLongestStringDT(hFont,
p_String*)

Description

Determines the longest string (measured in pixels) from a list of strings.

Remarks

This function is the same as Fnt_GetLongestString except that “DrawText” is used instead of “GetTextExtentPoint32” to measure the text size.  See Fnt_GetLongestString for more information.

Fnt_GetFont

Fnt_GetFont(hControl)

Description

Retrieves the font with which a control is currently drawing its text.

Parameters

hControlHandle to a control.

Returns

The handle to the font used by the control or 0 if the using the system font.

Fnt_GetFontAvgCharWidth

Fnt_GetFontAvgCharWidth(hFont: = "")

Description

Retrieves the average width of characters in a font (generally defined as the width of the letter “x”).  This value does not include the overhang required for bold or italic characters.

Parameters

hFontHandle to a logical font.  Set to null or 0 to use the default GUI font.

Returns

The average width of characters in the font, in pixels.

Calls To Other Functions

Remarks

This function should not be confused with Fnt_GetAverageCharWidth which returns a calulcated average character width.  Although the values are similar, this function returns a value as defined by the font’s designer.

The value returned by this function can be used to calculate the tab stop size for some common controls (Text, Tooltip, others?) and dialogs (MsgBox).  For these controls/dialogs, the tab stop size is the font’s average character width times 8.  Ex: Fnt_GetFontAvgCharWidth(hFont)*8.

Fnt_GetFontEmHeight

Fnt_GetFontEmHeight(hFont: = "")

Description

Retrieves the em height of characters in a font.

Parameters

hFontHandle to a logical font.  Set to null or 0 to use the default GUI font.

Returns

The em height of characters in the font.

Calls To Other Functions

Fnt_GetFontExternalLeading

Fnt_GetFontExternalLeading(hFont: = "")

Description

Retrieves the amount of extra leading space (if any) that an application may add between rows.

Parameters

hFontHandle to a logical font.  Set to null or 0 to use the default GUI font.

Returns

The external leading space of the font.

Calls To Other Functions

Fnt_GetFontHeight

Fnt_GetFontHeight(hFont: = "")

Description

Retrieves the cell height (ascent + descent) of characters in a font.

Parameters

hFontHandle to a logical font.  Set to null or 0 to use the default GUI font.

Returns

The height of characters in the font.

Calls To Other Functions

Fnt_GetFontInternalLeading

Fnt_GetFontInternalLeading(hFont: = "")

Description

Retrieves the amount of leading space (if any) inside the bounds set by the tmHeight member.

Parameters

hFontHandle to a logical font.  Set to null or 0 to use the default GUI font.

Returns

The internal leading space of the font.

Calls To Other Functions

Remarks

Accent marks and other diacritical characters may occur in the internal leading area.

Fnt_GetFontMaxCharWidth

Fnt_GetFontMaxCharWidth(hFont: = "")

Description

Retrieves the width of the widest character in a font.

Parameters

hFontHandle to a logical font.  Set to null or 0 to use the default GUI font.

Returns

The width of the widest character in the font, in pixels.

Calls To Other Functions

Observations

The value returned for this member can sometimes be unusually large.  For one font, I found a MaxCharWidth value that was 6 times larger than the AvgCharWidth.  For some fonts, a large discrepancy can be explained by the unusual nature of the font (symbols, math, etc.) but for other fonts, a very large discrepancy is harder to explain.  Note: These font values are set by the font’s designer.  They may be correct and/or intended (the most likely reality) or they may be incorrect/unintended (read: bug).

Fnt_GetFontMetrics

Fnt_GetFontMetrics(hFont: = "")

Description

Retrieves the text metrics for a font.

Parameters

hFontHandle to a logical font.  Set to null or 0 to use the default GUI font.

Returns

The address to a TEXTMETRIC structure.

Fnt_GetFontName

Fnt_GetFontName(hFont: = "")

Description

Retrieves the typeface name of the font.

Parameters

hFontHandle to a logical font.  Set to null or 0 to use the default GUI font.

Returns

The font name of the font.

Fnt_GetFontOptions

Fnt_GetFontOptions(hFont: = "")

Description

Retrieves the characteristics of a logical font for use in other library functions or by the AutoHotkey gui Font command.

Parameters

hFontHandle to a logical font.  Set to null or 0 to use the default GUI font.

Returns

Font options in the AutoHotkey “gui Font” format.  See the Options section for more information.

Calls To Other Functions

Options

Font options returned by this function may include the following.

boldFont weight is exactly 700, i.e. bold.
italicItalic font.
q{Quality}Output quality.  Ex: q3.  See the function’s static variables for a list of possible quality values.  This option is only returned if the quality value is not 2 (the AutoHotkey default).
s{SizeInPoints}Font size in points.  For example: s12
strikeStrikeout font.
underlineUnderlined font.
w{Weight}Font weight (thickness or boldness), which is an integer between 1 and 1000.  Ex: w600.  This option is only returned if the weight is not normal (400) and not bold (700).

If more than one option is included, it is delimited by a space.  For example: s12 bold italic

Remarks

Library functions that use font options in this format include Fnt_CreateFont and Fnt_ChooseFont.

Note: Color is an option of the AutoHotkey gui Font command and of the ChooseFont API and is included by these commands because text color is often set with the font.  However, text color is a control attribute, not a font attribute and so it is not (read: cannot be) collected/returned by this function.  If text color is to be included as one of the options sent to the AutoHotkey “gui Font” command or to the ChooseFont API, it must must be collected and/or set independently.

Fnt_GetLogicalFontName

Fnt_GetLogicalFontName(hFont)

Description

Retrieves the typeface name of the font.  See the Remarks section for more information.

Type

Helper/Debug.  Experimental (for now).  Subject to change.

Parameters

hFontHandle to a logical font.  Set to null or 0 to use the default GUI font.

Returns

Font options in the AutoHotkey “gui Font” format.  See the Options section for more information.

Remarks

The return value is the typeface specified when the font was created by the “CreateFont” or “CreateFontIndirect” API functions (can be null).  For stock or non-client fonts, this typeface is set by the operating system.  This typeface is used by the font mapping algorithm to find a physical font.  It may or may not match the typeface of a font that has been installed on the current computer.  This information might be useful when testing or debugging.

Fnt_GetLogicalFontOptions

Fnt_GetLogicalFontOptions(hFont: = "")

Description

Retrieves the attributes of a logical font in the AutoHotkey “gui Font” format.  See the Remarks section for more information.

Type

Helper/Debug.  Experimental (for now).  Subject to change.

Parameters

hFontHandle to a logical font.  Set to null or 0 to use the default GUI font.

Returns

Font options in the AutoHotkey “gui Font” format.  See the Options section for more information.

Options

Font options returned by this function may include the following.

boldFont weight is exactly 700, i.e. bold.
h{HeightInPixels}Font height in pixels.  Ex: h20.  This option is only returned if the font was created using the “h”eight option with a positive value (Ex: “h30”).  If is option is returned, the “s”ize option is not returned.
italicItalic font.
q{Quality}Output quality.  Ex: q3.  See the function’s static variables for a list of possible quality values.  This option is only returned if the quality value is not 2 (the AutoHotkey default).
s{SizeInPoints}Font size in points.  For example: s12
strikeStrikeout font.
underlineUnderlined font.
w{Weight}Font weight (thickness or boldness), which is an integer between 0 and 1000.  Ex: w600.  This option is only returned if the weight is not normal (400) and not bold (700).

If more than one option is included, it is delimited by a space.  For example: s12 bold italic

Remarks

These options represent the font attributes that were specified (explicitly or by default) when the font was created by the “CreateFont” or “CreateFontIndirect” API functions.  For stock or non-client fonts, these options are set by the operating system.  These options are used by the font mapping algorithm to find a physical font.  They may or may not match the attributes of the physical font.  Some options are explicitly set to default/don’t care values to force the font mapping algorithm to find the correct/best value for the font.  This information might be useful when testing or debugging.

If the font was created using the Fnt library, it’s possible that options only supported by the Fnt library are returned.  For example, if the height option was specified with a positive (and greater than 0) value when creating the font (Ex: “h25”), this function will return the “h”eight option instead of the “s”ize option.

Fnt_GetFontQuality

Fnt_GetFontQuality(hFont: = "")

Description

Get the font’s output quality.

Parameters

hFontHandle to a logical font.  Set to null or 0 to use the default GUI font.

Returns

The font’s output quality.  This value defines how carefully the graphics device interface (GDI) must attempt to match the logical font attributes to those of an actual physical font.  See the function’s static variables for a list of possible quality values.

Fnt_GetFontSize

Fnt_GetFontSize(hFont: = "")

Description

Retrieves the point size of a font.

Parameters

hFontHandle to a logical font.  Set to null or 0 to use the default GUI font.

Returns

The point size of the font.

Fnt_GetFontWeight

Fnt_GetFontWeight(hFont: = "")

Description

Retrieves the weight (thickness or boldness) of a font.

Parameters

hFontHandle to a logical font.  Set to null or 0 to use the default GUI font.

Returns

The weight of the font.  Possible values are from 1 to 1000.

Calls To Other Functions

Fnt_GetMenuFontName

Fnt_GetMenuFontName()

Description

Returns the font name of the font used in menu bars.

Calls To Other Functions

Remarks

This function gets the font name of the font used in menu bars without creating the font.

Fnt_GetMenuFontSize

Fnt_GetMenuFontSize()

Description

Returns the point size of the font that is used in menu bars.

Calls To Other Functions

Remarks

This function calculates the point size of the font used in menu bars without creating the font.

Fnt_GetMenuFontOptions

Fnt_GetMenuFontOptions()

Description

Returns the font options of the font that is used in menu bars.

Type

Helper function.

Calls To Other Functions

Remarks

This function converts the steps needed to collect the font options of the the font used in menu bars into a single function call.

Fnt_GetMessageFontName

Fnt_GetMessageFontName()

Description

Returns the font name of the font that is used in message boxes.

Calls To Other Functions

Remarks

This function gets the font name of the font used in message boxes without creating the font.

Fnt_GetMessageFontOptions

Fnt_GetMessageFontOptions()

Description

Returns the font options of the font that is used in message boxes.

Type

Helper function.

Calls To Other Functions

Remarks

This function converts the steps needed to collect the font options of the the font used in message boxes into a single function call.

Fnt_GetMessageFontSize

Fnt_GetMessageFontSize()

Description

Returns the point size of the font that is used in message boxes.

Calls To Other Functions

Remarks

This function calculates the point size of the font used in message boxes without creating the font.

Fnt_GetMultilineStringSize

Fnt_GetMultilineStringSize( hFont,  
 p_String,  
ByRef r_Width: = "",
ByRef r_Height: = "")

Description

Calculates the size of a multiline string for a font.  See the Remarks section for more information.

Parameters

hFontHandle to a logical font.  Set to null or 0 to use the default GUI font.
p_StringThe multiline string to be measured.  See the End-Of-Line Character(s) section for more information.
r_Width, r_Height[Output, Optional] These variables are loaded with the width and height of the string.

Returns

The address to a SIZE structure if successful, otherwise FALSE.

Calls To Other Functions

End-Of-Line Character(s)

This function uses the LF (line feed) and/or CR+LF (carriage return and line feed) characters in the string as delimiters to logically break the string into multiple lines of text.  The end-of-line (EOL) character(s) in the text must be in a DOS/Windows (EOL=CR+LF), Unix (EOL=LF), or DOS/Unix mix format.  A string in any other format must be converted to a DOS/Windows or Unix format before calling this function.

Remarks

This is a specialty function to determine the size of a multiline string.  The width of the widest line and the combined height of all of the lines is returned.  This information can be used to determine how much space the string will use when attached to a GUI control that supports multiple lines of text.

This function is not deprecated but new functions introduced in v3.0 of the library might be more appropriate for measuring text size.  See Measuring Text Size for more information.

Fnt_GetMultilineStringSizeDT

Fnt_GetMultilineStringSizeDT( hFont,  
 p_String,  
ByRef r_Width: = "",
ByRef r_Height: = "")

Description

Calculates the size of a multiline string for a font.

Remarks

This function is the same as Fnt_GetMultilineStringSize except that “DrawText” is used instead of “GetTextExtentPoint32” to measure the text size.  See Fnt_GetMultilineStringSize for more information.

This function is similar to Fnt_GetSize.  It is more efficient but has less flexibility than Fnt_GetSize.

Fnt_GetNonClientMetrics

Fnt_GetNonClientMetrics()

Description

Retrieves the metrics associated with the nonclient area of nonminimized windows.

Returns

The address to a NONCLIENTMETRICS structure if successful, otherwise FALSE.

Fnt_GetPos

Fnt_GetPos( hControl,  
ByRef X: = "",
ByRef Y: = "",
ByRef Width: = "",
ByRef Height: = "")

Description

Get the position and size of a GUI control.  See the Remarks section for more information.

Parameters

hControlHandle to a control.
X, Y, Width, HeightOutput variables.  [Optional] If defined, these variables contain the coordinates of the control relative to the client-area of the parent window (X and Y), and the width and height of the control (Width and Height).

Remarks

If using a DPI setting that is smaller or larger than the default/standard (Ex: 120 DPI, 144 DPI, or custom) and if using the DPIScale feature (AutoHotkey v1.1.11+, enabled by default), the values returned from the GUIControlGet,OutputVar,Pos command will reflect the calculations that were used by the DPIScale feature to create the control.  For example, if a control were created with the “x20 y20 w500 h200” options and if using 120 DPI, the actual position and size of the control will be “x25 y25 w625 h250”.  When the GUIControlGet,OutputVar,Pos command is used on this control, it returns values that reflect the original “x20 y20 w500 h200” options.  This function returns the actual position and/or size of the control regardless of the current display DPI.  It can be useful if the current display DPI is unknown and/or the disposition of the DPIScale feature is unknown.  In addition, this function works on all GUI controls whereas the GUIControlGet command only works on controls created using the AutoHotkey “gui Add” command.

The ControlGetPos and WinGetPos commands are not DPI-aware and so if only interested in the width and/or height values, these commands can be used on GUI controls.  Hint: The native AutoHotkey commands are more efficient and should be used whenever possible.

Fnt_GetSmCaptionFontName

Fnt_GetSmCaptionFontName()

Description

Returns the font name of the small caption font.

Calls To Other Functions

Remarks

This function gets the font name of the small caption font without creating the font.

Fnt_GetSmCaptionFontOptions

Fnt_GetSmCaptionFontOptions()

Description

Returns the font options of the small caption font.

Type

Helper function.

Calls To Other Functions

Remarks

This function converts the steps needed to collect the font options of the the small caption font into a single function call.

Fnt_GetSmCaptionFontSize

Fnt_GetSmCaptionFontSize()

Description

Returns the point size of the small caption font.

Calls To Other Functions

Remarks

This function calculates the point size of the small caption font without creating the font.

Fnt_GetStatusFontName

Fnt_GetStatusFontName()

Description

Returns the font name of the font used in status bars and tooltips.

Calls To Other Functions

Remarks

This function gets the font name of the font used in status bars and tooltips without creating the font.

Fnt_GetStatusFontOptions

Fnt_GetStatusFontOptions()

Description

Returns the font options of the font that is used in status bars and tooltips.

Type

Helper function.

Calls To Other Functions

Remarks

This function converts the steps needed to collect the font options for the status font into a single function call.

Fnt_GetStatusFontSize

Fnt_GetStatusFontSize()

Description

Returns the point size of the font that is used in status bars and tooltips.

Calls To Other Functions

Remarks

This function calculates the point size of the font used in status bars and tooltips without creating the font.

Fnt_GetTooltipFontName

Fnt_GetTooltipFontName()

Description

Returns the font name of the font used in tooltips.

Calls To Other Functions

Remarks

This function gets the font name of the font used in tooltips without creating the font.

This function is a clone of Fnt_GetStatusFontName.

Fnt_GetTooltipFontOptions

Fnt_GetTooltipFontOptions()

Description

Returns the font options of the font that is used in tooltips.

Type

Helper function.

Calls To Other Functions

Remarks

This function converts the steps needed to collect the font options for the font that is used in tooltips into a single function call.

Fnt_GetTooltipFontSize

Fnt_GetTooltipFontSize()

Description

Returns the point size of the font that is used in tooltips.

Calls To Other Functions

Remarks

This function calculates the point size of the font used in tooltips without creating the font.

This function is a clone of Fnt_GetStatusFontSize.

Fnt_GetSize

Fnt_GetSize( hFont,  
 p_Text,  
 p_MaxW: = 0,
ByRef r_Width: = "",
ByRef r_Height: = "")

Description

Calculates the width and height of text that will used in a GUI control.  See the Remarks section for more information.

Parameters

hFontHandle to a logical font.  Set to null or 0 to use the default GUI font.
p_TextThe string of text to be measured.
p_MaxWThe maximum width, in pixels, of the text.  [Optional] See the Maximum Width section for more information.
r_Width, r_Height[Output, Optional] These variables are loaded with the calculated width and height of the string.

Returns

The address to a SIZE structure.  The cx member contains the maximum width of the text.  The cy member contains the height of the text.

Maximum Width

The optional p_MaxW parameter is used to set the maximum width, in pixels, of the text contained in the p_Text parameter.  If unspecified, null, or zero (0) (the default), the maximum width is entirely determined by the text contained in the p_Text parameter which can contain end-of-line (EOL) sequences (LF or CR+LF) to break the text into multiple lines.  If p_MaxW contains a non-zero positive integer value, lines are automatically broken between words if a word extends past the maximum width.  EOL character(s) in the text also breaks the line.

Remarks

This is a general-purpose function to calculate the size of the text that will be display in a GUI control.  It will work for most controls with the following exceptions: 1) tab characters are not expanded and 2) prefix characters (i.e.  “&”) are not processed.

Warning: If a very large amount of text is specified, the “DrawText” API function may take an unusually long time to calculate the size.  If needed, limit the amount of the text that is passed to this function.  Setting the p_MaxW parameter to a reasonable limit (i.e. the width of the screen or less) can also improve response when a very large amount of text is specified.

Do not confuse this function with Fnt_GetFontSize.

Fnt_GetSizeForButton

Fnt_GetSizeForButton( hFont,  
 p_Text,  
 p_MaxW: = 0,
ByRef r_Width: = "",
ByRef r_Height: = "")

Description

Calculates the width and height of text that will used in a button control.  See the Remarks section for more information.

Parameters

hFontHandle to a logical font.  Set to null or 0 to use the default GUI font.
p_TextThe string of text to be measured.
p_MaxWThe maximum width, in pixels, of the string.  [Optional] See the Maximum Width section for more information.
r_Width, r_Height[Output, Optional] These variables are loaded with the calculated width and height of the string.

Returns

The address to a SIZE structure.  The cx member contains the maximum width of the text.  The cy member contains the height of the text.

Maximum Width

The optional p_MaxW parameter is used to set the maximum width, in pixels, of the text contained in the p_Text parameter.  If unspecified, null, or zero (0) (the default), the maximum width is entirely determined by the text contained in the p_Text parameter which can contain end-of-line (EOL) sequences (LF or CR+LF) to break the text into multiple lines.  If p_MaxW contains a non-zero positive integer value, lines are automatically broken between words if a word extends past the maximum width.  EOL character(s) in the text also breaks the line.

Remarks

This function is designed to calculate the size of the text that will displayed in a button control.  Buttons share some of the characteristics of other multiline controls (Ex: Edit control) but they have some unique characteristics which affect the size calculation.  These characteristics include but are not limited to:

  • Tabs.  Tab characters are not expanded,
  • Prefix.  Prefix characters are processed.  The ampersand (&) mnemonic-prefix character is a directive to underscore the character that follows and the double-ampersand (&&) mnemonic-prefix characters is a directive to draw a single ampersand.

This function can also be used to calculate the width of strings that will be used in other controls that have similar characteristics (Ex: Menu) but in most cases these controls do not support multiple lines and so the p_MaxW parameter should not be set and the string should not contain EOL characters.

Warning: If a very large amount of text is specified, the “DrawText” API function may take an unusually long time to calculate the size.  If needed, limit the amount of the text that is passed to this function.  Setting the p_MaxW parameter to a reasonable limit (i.e. the width of the screen or less) can also improve response when a very large amount of text is specified.

Fnt_GetSizeForEdit

Fnt_GetSizeForEdit( hFont,  
 p_Text,  
 p_MaxW: = 0,
ByRef r_Width: = "",
ByRef r_Height: = "")

Description

Calculates the width and height of text that will used in an Edit control.  See the Remarks section for more information.

Parameters

hFontHandle to a logical font.  Set to null or 0 to use the default GUI font.
p_TextThe string of text to be measured.
p_MaxWThe maximum width, in pixels, of the string.  [Optional] See the Maximum Width section for more information.
r_Width, r_Height[Output, Optional] These variables are loaded with the calculated width and height of the string.

Returns

The address to a SIZE structure.  The cx member contains the maximum width of the text.  The cy member contains the height of the text.

Maximum Width

The optional p_MaxW parameter is used to set the maximum width, in pixels, of the text contained in the p_Text parameter.  If unspecified, null, or zero (0) (the default), the maximum width is entirely determined by the text contained in the p_Text parameter which can contain end-of-line (EOL) sequences (LF or CR+LF) to break the text into multiple lines.  If p_MaxW contains a non-zero positive integer value, lines are automatically broken between words if a word extends past the maximum width.  EOL character(s) in the text also breaks the line.

Remarks

This function is designed to calculate the size of the text that will displayed in an Edit control.  The Edit control has spacing characteristics that are unique to most other controls.  Some of these characteristics include but are not limited to:

  • Tabs.  Tab characters are expanded to the default tab size.  The average character width is calculated differently for the Edit control than some other controls.

The calculated values returned by function do not factor in a left or right margin or a custom tab stop size.  To include these factors in the calculation, use Fnt_CalculateSize instead.

Warning: If a very large amount of text is specified, the “DrawText” API function may take an unusually long time to calculate the size.  If needed, limit the amount of the text that is passed to this function.  Setting the p_MaxW parameter to a reasonable limit (i.e. the width of the screen or less) can also improve response when a very large amount of text is specified.

Fnt_GetSizeForText

Fnt_GetSizeForText( hFont,  
 p_Text,  
 p_MaxW: = 0,
ByRef r_Width: = "",
ByRef r_Height: = "")

Description

Calculates the width and height of text that will used in a static control like the Text control.  See the Remarks section for more information.

Parameters

hFontHandle to a logical font.  Set to null or 0 to use the default GUI font.
p_TextThe string of text to be measured.
p_MaxWThe maximum width, in pixels, of the string.  [Optional] See the Maximum Width section for more information.
r_Width, r_Height[Output, Optional] These variables are loaded with the calculated width and height of the string.

Returns

The address to a SIZE structure.  The cx member contains the maximum width of the text.  The cy member contains the height of the text.

Maximum Width

The optional p_MaxW parameter is used to set the maximum width, in pixels, of the text contained in the p_Text parameter.  If unspecified, null, or zero (0) (the default), the maximum width is entirely determined by the text contained in the p_Text parameter which can contain end-of-line (EOL) sequences (LF or CR+LF) to break the text into multiple lines.  If p_MaxW contains a non-zero positive integer value, lines are automatically broken between words if a word extends past the maximum width.  EOL character(s) in the text also breaks the line.

Remarks

This function is designed to calculate the size of the text that will displayed in a static control like the Text control.  Text controls share some of the characteristics of other multiline controls (Ex: Edit control) but they have some unique characteristics which affect the size calculation.  These characteristics include but are not limited to:

  • Tabs.  Tab characters are expanded.  Note: The default (and only) tab stop size for a static control is different than the default tab stop size for other GUI controls like the Edit control.

Warning: If a very large amount of text is specified, the “DrawText” API function may take an unusually long time to calculate the size.  If needed, limit the amount of the text that is passed to this function.  Setting the p_MaxW parameter to a reasonable limit (i.e. the width of the screen or less) can also improve response when a very large amount of text is specified.

Fnt_GetSizeForTextNoPrefix

Fnt_GetSizeForTextNoPrefix( hFont,  
 p_Text,  
 p_MaxW: = 0,
ByRef r_Width: = "",
ByRef r_Height: = "")

Description

Calculates the width and height of text that will used in a static control like the Text control.

Remarks

This function is the same as Fnt_GetSizeForText except that the DT_NOPREFIX format is also used when calculating the size.  This can be useful when the text is used on a text control that has the SS_NOPREFIX style.  See Fnt_GetSizeForText for more information.

Fnt_GetStringSize

Fnt_GetStringSize( hFont,  
 p_String,  
ByRef r_Width: = "",
ByRef r_Height: = "")

Description

Calculates the width and height (in pixels) of a string of text.

Parameters

hFontHandle to a logical font.  Set to null or 0 to use the default GUI font.
p_StringThe string to be measured.
r_Width, r_HeightOutput variables.  [Optional] These variables are loaded with the width and height of the string.

Returns

The address to a SIZE structure.  The cx member contains the width of the string.  The cy member contains the height of the string.

Remarks

This function is designed to get the size of a single line of text.  End of line (EOL) characters (LF or CR+LF) in the string are not considered when calculating the height of the text.  Use Fnt_GetMultilineStringSize to get the size of multiline text.

Tab characters are not expanded when calculating the size of text.  If needed, use Fnt_GetTabbedStringSize instead.

Fnt_GetStringSizeDT

Fnt_GetStringSizeDT( hFont,  
 p_String,  
ByRef r_Width: = "",
ByRef r_Height: = "")

Description

Calculates the width and height (in pixels) of a string of text.

Remarks

This function is the same as Fnt_GetStringSize except that “DrawText” is used instead of “GetTextExtentPoint32” to measure the text size.  See Fnt_GetStringSize for more information.

Fnt_GetStringWidth

Fnt_GetStringWidth(hFont,
p_String)

Description

Calculates the width (in pixels) of a string of text.

Parameters

hFontHandle to a logical font.  Set to null or 0 to use the default GUI font.
p_StringThe string to be measured.

Returns

The width of the specified string, in pixels.

Remarks

This function is designed to get the width of a single line of text.  End of line (EOL) characters (LF or CR+LF) in the string are not considered when calculating the width of the text.  Use Fnt_GetMultilineStringSize or Fnt_GetSize to get the size of multiline text.

Tab characters are not expanded when calculating the size of text.  This library includes a number of functions that expand tab characters when calculating the size of text.  Fnt_CalculateSize is the most flexible but there a number of other specialty functions that might be more useful.

Fnt_GetStringWidthDT

Fnt_GetStringWidthDT(hFont,
p_String)

Description

Calculates the width (in pixels) of a string of text.

Remarks

This function is the same as Fnt_GetStringWidth except that “DrawText” is used instead of “GetTextExtentPoint32” to measure the text size.  See Fnt_GetStringWidth for more information.

Fnt_GetSysColor

Fnt_GetSysColor(p_DisplayElement)

Description

Retrieves the current color of the specified display element.  Display elements are the parts of a window and the display that appear on the system display screen.

Parameters

p_DisplayElementDisplay element.  A complete list of display elements can be found here.

Type

Internal function.  Subject to change.  Do not use.

Returns

The display element color in an AutoHotkey hexadecimal value.  Ex: 0x12FF7B.

Remarks

The return value always contains 6 hexadecimal digits.  Ex: 0x00FF00.  To convert to a 6-digit RGB color value, simply delete the leading “0x” characters.

Fnt_GetTabbedStringSize

Fnt_GetTabbedStringSize( hFont,  
 p_String,  
ByRef r_Width: = "",
ByRef r_Height: = "",
 p_TabStops*  )

Description

Calculates the width and height (in pixels) of a string of text.  If the string contains one or more tab characters, the width of the string is based upon the specified tab stops.

Parameters

hFontHandle to a logical font.  Set to null or 0 to use the default GUI font.
p_StringThe string to be measured.
r_Width, r_HeightOutput variables.  [Optional] These variables are loaded with the width and height of the string.
p_TabStopsZero or more tab stop positions in pixels.  The tab stops must be set in increasing order.  Ex: 125, 200, 295.  If no tab stop are specified, tabs are expanded to eight times the average character width, i.e.  32 dialog template units.  Note: This is the default tab stop size of the Edit, ListBox, and some other controls.  If only one tab stop is set, the tab stops are separated by the distance specified by the first value.  For example, setting p_TabStops to 111 is the equivalent of setting p_TabStops to 111, 222, 333, etc.

Returns

The address to a SIZE structure.  The cx member contains the width of the string.  The cy member contains the height of the string.

Tab Stop Size

This function sets the tab stop in pixels.  For some GUI controls and common dialogs, the tab stop size is measured in pixels (Example: Text control and MsgBox dialog).  For other GUI controls (Ex: Edit, ListBox, etc.), the tab stop is measured in dialog template units.  To ensure that this function works correctly when the text is displayed on a GUI control that uses dialog template units when setting the tab stop, the tab stop size should be an exact factor of a dialog template unit for the specified font.

Remarks

This function is designed to get the size of a single line of text.  End of line (EOL) characters (LF or CR+LF) in the string are not considered when calculating the height of the text.

This function does not process prefix characters (i.e.  “&”).  If the string contains prefix characters and is to used in a GUI control that processes prefix characters (Ex: Text control without the SS_NOPREFIX style), the calculated width will be incorrect.  In these cases, use a function that process prefix characters (Ex: Fnt_CalculateSize or Fnt_GetSizeForText).

Observations

If the p_TabStops contains more than one tab stop, tab stop values for all tabs defined in p_String must be specified, otherwise the default size, i.e.  8 average characters (32 dialog template units), is used for all tab stops.

Fnt_GetTotalRowHeight

Fnt_GetTotalRowHeight(hFont,
p_NbrOfRows)

Description

Calculates the height of a given number of rows of text for a font.

Parameters

hFontHandle to a logical font.  Set to null or 0 to use the default GUI font.
p_NbrOfRowsRows of text.  Ex: 12.  Partial rows can be specified.  Ex: 5.25.

Returns

The height of the rows of text, in pixels.

Calls To Other Functions

Remarks

This function calculates the total height by adding up the font height for each row, including the space between each row (external leading) if there is more than one row.  This calculation was extracted from the AutoHotkey source and is the same or similar calculation used by AutoHotkey when the r{NumberOfRows} GUI option is used.  Note: This calculation does not include any extra space that a GUI control may need in order to correctly display the text in the control.  Ex: Edit control.

Note: Although this calculation is able to duplicate the same height as the AutoHotkey r{NumberOfRows} GUI option, the result is inaccurate for most (all?)  GUI controls if the font contains a non-zero external leading value and more than 1 row is specified.  See Row Height for more information.

Fnt_GetWindowColor

Fnt_GetWindowColor()

Description

Retrieves the current window (background) color.

Type

Internal function.  Subject to change.  Do not use.

Calls To Other Functions

Fnt_GetWindowTextColor

Fnt_GetWindowTextColor()

Description

Retrieves the current window text color.

Type

Internal function.  Subject to change.  Do not use.

Calls To Other Functions

Fnt_HorzDTUs2Pixels

Fnt_HorzDTUs2Pixels(hFont,
p_HorzDTUs)

Description

Converts horizontal dialog template units to pixels for a font.

Returns

The width of the specified horizontal dialog template units, in pixels.

Calls To Other Functions

Remarks

This function is just a call to Fnt_DialogTemplateUnits2Pixels to only convert horizontal dialog template units.

Fnt_IsFixedPitchFont

Fnt_IsFixedPitchFont(hFont)

Description

Determines if a font is a fixed pitch font.

Parameters

hFontHandle to a logical font.

Returns

TRUE if the font is a fixed pitch font, otherwise FALSE.

Calls To Other Functions

Fnt_IsFont

Fnt_IsFont(hFont)

Description

Determines if the hFont parameter contains the handle to valid logical font.

Parameters

hFontHandle to a logical font.

Returns

TRUE if hFont contains the handle to valid logical font, otherwise FALSE.

Remarks

TRUE is returned if hFont contains the handle to a stock font (Ex: Default GUI font).

Fnt_IsTrueTypeFont

Fnt_IsTrueTypeFont(hFont)

Description

Determines if a font is a TrueType font.

Parameters

hFontHandle to a logical font.

Returns

TRUE if the font is a TrueType font, otherwise FALSE.

Calls To Other Functions

Fnt_Pixels2DialogTemplateUnits

Fnt_Pixels2DialogTemplateUnits( hFont,  
 p_Width,  
 p_Height: = 0,
ByRef r_HorzDTUs: = "",
ByRef r_VertDTUs: = "")

Description

Converts pixels to dialog template units for a font.

Parameters

hFontHandle to a logical font.
p_WidthWidth, in pixel.
p_HeightHeight, in pixels.
r_HorzDTUs, r_VertDTUsOutput variables.  [Optional] These variables are loaded with the horizontal and vertical dialog template units for the specified width and height.

Returns

The address to a SIZE structure.  The cx member of the SIZE structure contains the horizontal dialog template units for the specified width.  The cy member contains the vertical dialog template units for the specified height.

Calls To Other Functions

Fnt_RemoveFontFile

Fnt_RemoveFontFile(p_File,  
p_Private,  
p_Hidden: = False)

Description

Remove the font(s) added with Fnt_AddFontFile.

Type

Experimental.  Subject to change.

Parameters

Same parameters as Fnt_AddFontFile.  Use the same parameter values that were used to add the font(s).

Returns

The number of the fonts removed if successful, otherwise FALSE.

Remarks

See the Remarks section of Fnt_AddFontFile for more information.

Fnt_RGB2ColorName

Fnt_RGB2ColorName(p_ColorRGB,  
p_ReturnDefaultName: = False)

Description

Convert a RGB value into one of 16 color names if a match is found.  See the function’s static variables for a list of supported color names.

Type

Internal function.  Subject to change.  Do not use.

Parameters

p_ColorRBGAn RGB integer.  Examples: 0xFF0000, 16711680.
p_ReturnDefaultNameSee the Return Default Name section for more information.

Returns

A color name (Ex: “Blue”) if a match is found, otherwise the original value is returned.

Calls To Other Functions

Return Default Name

The p_ReturnDefaultName parameter allows the developer to determine what color name (if any) is returned if the p_ColorRBG contains the default text color.

If p_ReturnDefaultName is set to TRUE, “Default” is returned if p_ColorRGB contains the default text color.  If p_ColorRGB contains any other value, it is processed normally.

If p_ReturnDefaultName is set to FALSE (the default), the p_ColorRGB parameter is processed normally.

Fnt_SetFont

Fnt_SetFont(hControl,  
hFont: = "",
p_Redraw: = False)

Description

Sets the font that the control is to use when drawing text.

Parameters

hControlHandle to the control.
hFontHandle to a logical font.  Set to null or 0 to use the default GUI font.
p_RedrawSpecifies whether the control should be redrawn immediately upon setting the font.  If set to TRUE, the control redraws itself.

Remarks

The size of the control does not change as a result of receiving this message.  To avoid clipping text that does not fit within the boundaries of the control, the program should set/correct the size of the control window before the font is set.

Update 20150615: A recent update of Windows 7 (it appears to be other versions of Windows as well) has changed how the tooltip control responds to certain messages.  The tooltip may no longer automatically redraw when the WM_SETFONT message is sent.  Worse yet, if the p_Redraw parameter is set to TRUE, the WM_SETFONT message may deactivate the tooltip.  One workaround is to send the WM_SETFONT message (this function) with p_Redraw set to FALSE (the default) and then send the TTM_UPDATE message (call Fnt_UpdateTooltip) immediately afterwards.  When used together, these functions will set the font of the tooltip control and redraw the tooltip control without deactivating the tooltip.

Fnt_SetTooltipFont

Fnt_SetTooltipFont(p_Name: = "",
p_Options: = "")

Description

Creates a font and sets the last created tooltip control to use the font.  See the Usage Notes section for more information.

Type

Helper function.

Parameters

p_NameName of the font.  [Optional] If null (the default), the default GUI font name is used.
p_OptionsFont options.  [Optional] See the Options section in Fnt_CreateFont for more information.

Returns

A handle to a logical font.

Credit

Idea and and proof of concept of combining all of this functionality into a single function from rommmcek.

Calls To Other Functions

Usage Notes

This helper function 1) finds the last created tooltip, 2) creates a font, and 3) sets the font to the tooltip.  There are a few notes/considerations:

This function should be called immediately after a tooltip is created using the AutoHotkey Tooltip command.  For example:

Tooltip Brown Chicken`, Brown Cow
hTTFont:=Fnt_SetTooltipFont("Arial","s14")

For completeness, the font created for the tooltip should be destroyed after the tooltip is destroyed.  For example:

Tooltip Brown Chicken`, Brown Cow
hTTFont:=Fnt_SetTooltipFont("Arial","s14")
Sleep 2000
Tooltip  ;-- Destroy the tooltip
Fnt_DeleteFont(hTTFont)

Even if the tooltip text is updated many times, this function should only be called once for every tooltip control created.  For example:

Tooltip Brown Chicken                       ;-- New tooltip control is created
hTTFont:=Fnt_SetTooltipFont("Arial","s14")  ;-- Font for tooltip is created and set
Sleep 2000
Tooltip Brown Cow                           ;-- New text, same tooltip control
;-- No need to set/update the font here
Sleep 2000
Tooltip                                     ;-- The tooltip control is destroyed
Fnt_DeleteFont(hTTFont)

AutoHotkey can create up to 20 unique tooltips.  A font can be created and set for each.  For example:

;-- Create tooltips
Tooltip Brown Chicken,100,100,1
hTTFont1:=Fnt_SetTooltipFont("Arial","s12")
Sleep 1000
Tooltip Brown Cow,200,150,2
hTTFont2:=Fnt_SetTooltipFont("Arial","s16")
Sleep 1000
Tooltip Once upon a time...,300,200,3
hTTFont3:=Fnt_SetTooltipFont("Arial","s20")
Sleep 2000

;-- Destroy tooltips
Tooltip,,,,1
Fnt_DeleteFont(hTTFont1)
Sleep 1000
Tooltip,,,,2
Fnt_DeleteFont(hTTFont2)
Sleep 1000
Tooltip,,,,3
Fnt_DeleteFont(hTTFont3)
Sleep 1000

Although this function gives the developer the ability to easily change the font on a tooltip, this change occurs after AutoHotkey creates and displays the tooltip.  The user may see the tooltip window resize when the new font is set.  In some cases, the tooltip window may even flash when the font is set or when tooltip window is resized.  In most cases, the change is barely noticeable, if at all.  However, for tooltips with a lot of text, the change may be very noticeable.

Fnt_String2DialogTemplateUnits

Fnt_String2DialogTemplateUnits( hFont,  
 p_String,  
ByRef r_HorzDTUs: = "",
ByRef r_VertDTUs: = "")

Description

Converts a string to dialog template units for a font.

Parameters

hFontHandle to a logical font.  Set to null or 0 to use the default GUI font.
p_StringThe string to be measured.
r_HorzDTUs, r_VertDTUsOutput variables.  [Optional] These variables are loaded with the horizontal and vertical dialog template units for the specified string.

Returns

The address to a SIZE structure.  The cx member of the SIZE structure contains the horizontal dialog template units for the specified string.  The cy member contains the vertical dialog template units.

Calls To Other Functions

Fnt_String2DialogTemplateUnitsDT

Fnt_String2DialogTemplateUnitsDT( hFont,  
 p_String,  
ByRef r_HorzDTUs: = "",
ByRef r_VertDTUs: = "")

Description

Converts a string to dialog template units for a font.

Remarks

This function is the same as Fnt_String2DialogTemplateUnits except that “DrawText” is used instead of “GetTextExtentPoint32” to measure the text size.  See Fnt_String2DialogTemplateUnits for more information.

Fnt_TruncateStringToFit

Fnt_TruncateStringToFit(hFont,
p_String,
p_MaxW)

Description

Returns a string, truncated if necessary, that is less than or equal to a specified maximum width, in pixels.

Parameters

hFontHandle to a logical font.  Set to null or 0 to use the default GUI font.
p_StringThe string to process.
p_MaxWThe maximum width for the return string, in pixels.

Returns

A string with a width (measured in pixels) that is less than or equal to the value in p_MaxW.

Calls To Other Functions

Remarks

Common control characters like tab, carriage control, and line feed are always counted but they may or may not contain a size (width and height).  Every font is different.  Note: Tab characters are never expanded by this function.

Fnt_TruncateStringWithEllipsis

Fnt_TruncateStringWithEllipsis(hFont,
p_String,
p_MaxW)

Description

Similar to Fnt_TruncateStringToFit except that if the string is truncated, the end of a string is replaced with an ellipses.

Parameters

hFontHandle to a logical font.  Set to null or 0 to use the default GUI font.
p_StringThe string to process.
p_MaxWThe maximum width for the return string, in pixels.

Returns

A string with a width (measured in pixels) that is less than or equal to the value in p_MaxW.

Remarks

This function is designed to truncate a single line of text.  Tab characters are not expanded when calculating the size but if the returned text contains tab characters, the tab characters may by expanded, depending on the control.  End-of-line (EOL) characters (LF or CR+LF) are treated as regular characters and do not break the line.  The height of the text is considered to be the height the specified font.  However, if the returned text contains EOL characters, the text may display on multiple lines, depending on the control.

The space calculated for tab characters varies from font to font.  For most fonts, the tab characters is given no size (0 pixels) but for other fonts, it’s given some non-zero value.  It’s unclear how much space is calculated for an EOL character but it’s some non-zero value.

Fnt_TwipsPerPixel

Fnt_TwipsPerPixel(ByRef X: = "",
ByRef Y: = "")

Description

Determines the number of twips (abbreviation of “twentieth of an inch point”) for every pixel on the screen.

Parameters

X, YOutput variables.  [Optional] These variables are loaded with the number of twips for each pixel along the screen width (X) and height (Y).

Returns

The address to a SIZE structure.  The cx member of the SIZE structure contains the number of twips for each pixel along the screen width.  The cy member contains the number of twips for each pixel along the screen height.

Fnt_UpdateTooltip

Fnt_UpdateTooltip(hTT)

Description

Forces the tooltip to be redrawn.

Parameters

hTTHandle to the tooltip control.

Remarks

See the Remarks section of Fnt_SetFont for more information.

Fnt_VertDTUs2Pixels

Fnt_VertDTUs2Pixels(hFont,
p_VertDTUs)

Description

Converts vertical dialog template units to pixels for a font.

Returns

The height of the specified vertical dialog template units, in pixels.

Calls To Other Functions

Remarks

This function is just a call to Fnt_DialogTemplateUnits2Pixels to only convert vertical dialog template units.

Add-On Functions

Add-On functions are functions stored in separate library files.  For example, Fnt_SpecialFunction.ahk.  They must be included separately in order to be used and they require the Fnt library in order to run.  In some cases, add-on functions may require other libraries in order to run.

Summary
Functions
Fnt_AutoFormatTabbedTextFormat tab-delimited text so the columns will align correctly when displayed.
Fnt_ChooseFontDlgAn alternative to the Fnt_ChooseFont function.
Fnt_ChooseFontDlg_ChooseColorCreates a Color dialog box that enables the user to select a color.
Fnt_ChooseFontDlg_SBSetTextSet the text in the specified part of a status bar.
Fnt_HardWordBreakInserts hard line breaks into a string of text so that the maximum width of each line is less than or equal to a specified width, in pixels.
Fnt_RandomFontGets a random font.
Fnt_RandomTTFontGets a random True Type font.
Fnt_RandomTTFPFontGets a random fixed pitch True Type font.
Fnt_RandomTTVPFontGets a random variable pitch True Type font.

Functions

Fnt_AutoFormatTabbedText

Fnt_AutoFormatTabbedText(hFont,  
p_Text,  
p_TabStopSize: = 0,
p_Options = "")

Description

Format tab-delimited text so the columns will align correctly when displayed.

Parameters

hFontHandle to a logical font.  Set to 0 to use the default GUI font.  See the Non-client Fonts section for additional values.
p_TextThe tab-delimited text to be formatted.
p_TabStopSizeThe tab stop size, in pixels.  See the Tab Stop Size section for more information.
p_OptionsSee the Options section for more information.

Returns

Text formatted to support the specified parameter values.

Calls To Other Functions

Edit Control

The Edit control is certainly one of the controls that can be used to display the text formatted by this function.  However, column alignment is accomplished by adding additional tab characters where needed.  These extra tab characters are included in the data displayed in the Edit control that the user can subsequently select and copy.  A better approach for the Edit control might be to change the control’s tab stop positions so that columns align without adding tab characters.  The Edit_AutoSetTabStops add-on function from the Edit library might be a better solution for the Edit control.

End-Of-Line Character(s)

The end-of-line (EOL) character(s) in the p_Text parameter must be in a DOS/Windows (EOL=CR+LF), Unix (EOL=LF), or DOS/Unix mix format.  A document in any other format must be converted to a DOS/Windows or Unix format before calling this function.

For the return value, the EOL character(s) are determined by the EOL option (p_Options parameter).  The default is the linefeed (i.e.  “`n”) character which is the AutoHotkey default.  This EOL character is frequently used when populating or extracting text to/from GUI controls.

Escape Characters

Most of the assignment options (p_Options parameter) support the following escape sequences for the following special characters.

\dDouble quote
\fForm feed
\nNew line
\rReturn
\sSpace
\tTab
\vVertical tab

Note: For some of these characters, a standard AutoHotkey escape sequence character (Ex: “`n”) can be used instead.

Options

The following options are supported.

EOL={EndOfLineChars}This option sets the end-of-line (EOL) character(s) for the returned text.  Ex: EOL=`r`n.  See the End-Of-Line Character(s) section for more information.
FirstRowIsHeaderThis option removes the first row from p_Text and assigns the value to the Header option.  If the HeaderUL option is also set, this option allows the header to displayed followed by underline characters.  If the Header option is specified after this option, the header record in the text is replaced with a custom header.
Header={ColumnHeader(s)}Tab-delimited column header(s).  Ex: Header=Col1`tCol2`tCol3.  If the option value contains one or more space characters, enclose the the entire value in double quotes.  Ex: Header=”Col 1`tCol 2`tCol 3”.  Note: If there are more Header columns than data columns, blank/empty data columns will display on the right.  Also, a column header can increase the column width significantly.  Assign with care.
HeaderUL={UnderlineChar(s)}Character(s) used to underline column headers.  Ex: HeaderUL=-.  The character(s) are automatically repeated until the sequence of characters is the width of the column header.  This option is only used if the FirstRowIsHeader or Header option is used.
NoPrefixWhen specified, the DT_NOPREFIX format is included when calculating the size of the text.  This format turns off processing of prefix characters.  This is option is useful if the control/dialog does not process prefix characters (i.e. ampersand (“&”)) and the text might include these characters.  Note: This option is automatically added in some cases.  See the Tab Stop Size section for more information.

A few notes...

Options are applied in the order they defined.  To use more than one option, include a space between each option.  For example: “NoPrefix EOL=`n”

Non-client Fonts

To avoid having to temporarily create commonly used non-client fonts before calling this function, the hFont parameter can also be set to the following string values:

CaptionUse a font with the same attributes as the caption font.
MenuUse a font with the same attributes as the font used in menu bars.
Message, MsgBoxUse a font with the same attributes as the font used in message boxes.
SmCaptionUse a font with the same attributes as the small caption font.
Status, TooltipUse a font with the same attributes as the font used in status bars and tooltips.

Additional notes...

Although all non-client fonts are supported, only the fonts for non-client components that can support multiple lines, i.e. message boxes and tooltips, have any practical value for this function.

Tab Stop Size

The p_TabStopSize parameter is used to specify the tab stop size, in pixels, that will used to format the data.  Although some controls can be set more than one tab stop size (Ex: Edit, ListBox, and others), this function only works on controls where a single tab stop size is set.

If not specified or if set to 0 (the default), the default tab stop for many controls or dialogs (Ex: Text, Tooltips, et. al.) is used.

Alternately, this parameter can be set to the name of the control/dialog that will used.  If this is done, the default tab size for that control/dialog is used.  In addition, control-specific options (Ex: “NoPrefix”) are automatically added to the p_Options parameter when appropriate.  The following control names are currently supported.

Edit, Message, MsgBoxThe default tab size for the Edit control is used and the “NoPrefix” option is automatically added to p_Options.
TooltipThe default tab size for this control is used and the “NoPrefix” option is automatically added to p_Options.
Anything elseThe default tab size for most controls (not “Edit”) is used.  No options are automatically added to p_Options.

Remarks

This function is designed to add additional tab characters (if needed) to tab-delimited data so that the columns align when the data is displayed.  To accomplish this task, the data is processed twice.  In the first pass, the number of columns and maximum width for each column is identified.  If the maximum width for a column is an exact factor of the tab stop size, the maximum width for the column is increased by one tab stop size so that the data in the column does not bump up directly next to the following column.  In the second pass, tab characters are added to the text where needed so that all columns will align correctly when displayed.  In each pass, every field in the data is measured to determine the width of the field.

The resources used by this function are very reasonable if the number of or fields to process is relatively small (300 or less).  However, if there are a large (>300) or very large (>600) number of fields to process, the response time can range anywhere from noticeable to significant (>1 second).  If there is possibility for a large number of fields to be processed, performance can be improved by setting SetBatchLines to a higher value before calling this function.  For example:

SetBatchLines 100ms
FormattedText:=Fnt_AutoFormatTabbedText(hFont,...)
SetBatchLines 10ms  ;-- This is the system default

Fnt_ChooseFontDlg

Fnt_ChooseFontDlg( p_Owner: = "",
ByRef r_Name: = "",
ByRef r_Options: = "",
 p_Effects: = True,
 p_Flags: = 0,
 p_HelpHandler: = "")

Description

An alternative to the Fnt_ChooseFont function.

Type

Add-on function.  Preview/Experimental.

Parameters

p_OwnerOwner GUI.  Set to 0 for no owner.  See the Owner section for more information.
r_NameTypeface name.  [Input/Output] On input, this variable can contain the default typeface name.  On output, this variable will contain the selected typeface name.
r_OptionsFont options.  [Input/Output] See the Options section for the details.
p_EffectsFlags to determine what GUI controls are shown.  See the Effects section for more information.
p_Flags[Advanced Feature] Additional ChooseFont bit flags.  [Optional] The default is 0 (no additional flags).  See the ChooseFont Flags section for more information.
p_HelpHandlerName of a developer-created function that is called when the the user presses the Help button on the dialog.  [Optional] See the Help Handler section for the details.  Note: The CF_SHOWHELP flag is automatically added if this parameter contains a valid function name.

Returns

TRUE if a font was selected, otherwise FALSE is returned if the dialog was canceled or if an error occurred.

Calls To Other Functions

ChooseFont Flags

This function and associated dialog is designed to emulate the ChooseFont dialog when possible.  Much of the flexibility this dialog is available via a large number of ChooseFont flags.  For this function, the flags are determined by fixed values, options in the r_Options parameter, and the value of the p_Effects parameter.  Although the flags set by these conditions will handle the needs of the majority of developers, there are additional ChooseFont flags that could provide additional value.

The p_Flags parameter is used to add additional ChooseFont flags to control the operation of the FntCFDlg window.  Note carefully that some of the ChooseFont flags are not supported by this function.  In addition, there are a few custom ChooseFont flags that are only available to functions in the Fnt library.  See the function’s static variables for a list of possible flag values.

Warning: This is an advanced feature.  Including invalid or conflicting flags may produce unexpected results.  In addition, some of the ChooseFont flags may conflict with some of the flags set in the p_Effects parameter.  Be sure to test throroughly.

Compatibility

At this writing, this function is mostly backwards compatible to the features and syntax of the functions that use the ChooseFont API in the Fnt library (Fnt_ChooseFont) and in the Dlg2 library (Dlg_ChooseFont).  There many possible exceptions but often just the function name needs to be changed in order to use this add-on function.  For example, the following call to Fnt_ChooseFont function can easily changed.

From:
Fnt_ChooseFont(hMyGUI,$FontName,$FontOptions)

To:
Fnt_ChooseFontDlg(hMyGUI,$FontName,$FontOptions)

Effects

The p_Effects parameter is used to determine what GUI controls are shown.  The following are the primary values for this parameter:

TRUE (1) or CFD_ALL (0x1)Show all GUI controls except the status bar.  This is the default value.  The controls shown are similar to what is shown when the CF_EFFECTS flags is included when calling the ChooseFont API function.
2 or CFD_ALLXCOLOR (0x2)Show all GUI controls except the Color combo box and the status bar.  The controls shown are similar to what is shown when the CF_EFFECTS flag in not included when calling the ChooseFont API function.
FALSE (0)This will produce the same results as CFD_ALLXCOLOR (0x2) except that it cannot be combined with any other value.  To combine with other values, use CFD_ALLXCOLOR (0x2) instead.

Alternatively, any combination of following values can be used.  These values can be used independently or they can be combined with the previous values except where noted.

CFD_TYPEFACE (0x10)Show the Font Name combo box.
CFD_SIZE (0x20)Show the Size combo box.
CFD_STYLE (0x40)Show the Style group.
CFD_QUALITY (0x80)Show the Quality drop down list.
CFD_COLOR (0x100)Show the Color combo box.
CFD_SAMPLETEXT (0x200)Show the Sample Text group.
CFD_STATUSBAR (0x400)Show the status bar.
CFD_DISABLETYPEFACE (0x1000)Disable the Font Name combo box.  This flag is only used if the Font Name combo box is showing.
CFD_DISABLESIZE (0x2000)Disable the Size combo box.  This flag is only used if the Size combo box is showing.
CFD_DISABLESTYLE (0x4000)Disable the controls in the Style group.  This flag is only used if the Style group is showing.
CFD_DISABLEQUALITY (0x8000)Disable the Quality drop down list.  This flag is only used if the Quality drop down list is showing.
CFD_DISABLECOLOR (0x10000)Disable the Color combo box.  This flag is only used if the Color combo box is showing.

Additional...

Not showing a GUI control is much different that just disabling it.  If a control or group of controls are not shown, the associated value(s) are not returned.  For example, if the Color combo box is not shown, the color option (Ex: “cBlue”) is not returned.  However, if a control is disabled, the initial value of the control cannot be modified by the user and is returned as is.  For example if the initial value of the Size combo box is 12 and the control is disabled, the user will see the Size combo box, the size 12 will be selected, but user will not be able to modify the size.  When the function returns, the size option will return with the selected value (Ex: “s12”).  If hiding or disabling any of the controls that affect the value of the font name or options, be sure to test thoroughly.

Height

The “h{HeightInPixels}” option (r_Options parameter) allows the developer to specify a font size based on height instead of point size.  This option has the same precedence as the “s”ize option.  If both the “h” and “s” options are specified, the last one specified is used.

If the height value is positive (Ex: “h30”), the font mapper matches it against the cell height (ascent + descent) of the available fonts and will set/select the closest point size value.

If the height value is negative (Ex: “h-25”), the font mapper matches the absolute value against the em height (cell height less internal leading) of the available fonts and will set/select the closest point size value.

Note: This is an “input only” option.  The “h”eight option is not returned.  Instead, the function returns the point size selected.  Ex: “s16”.

Help Handler

The Help Handler is an optional developer-created function that is called when the user presses the Help button on the dialog.

The function must have one parameter -- an event object.  For lack of a better name, we’ll call it EO.  The following Event Object properties are available:

EffectsEffects flags.  This contains all of the active Effects flags.  They are not necessarily the same flags set in the p_Effects parameter.  Flags that are implicitly set because a flag covers multiple controls (Ex: CFD_ALL), are explicitly set in this property.  This keeps the developer from having to test for all possible conditions (Ex: CFD_ALL or CFD_ALLXCOLOR or CFD_SIZE).  Instead, only the specific condition (Ex: CFD_SIXE) needs to be tested.
EventThe name of the event.  For the help handler, the event is “Help”.
FlagsChooseFont flags.  This contains all of the ChooseFont flags that that have been set.  They are not necessarily the same as the flags set in the p_Flags parameter.  They also contain flags that are automatically added by this function.
FontNameThe current font name.  This is not necessarily the final font name that the Fnt_ChooseFontDlg function will return.
FontOptionsThe current font options.  This not necessarily the final version of the font options that the Fnt_ChooseFontDlg function will return.
GUIThe GUI name.  Ex: “FntCFDlg”.
hDlgThe handle to the FntCFDlg window.
hSBThe handle to the status bar.  This value is zero (0) if the status bar is not showing.

Hint: The EO properties are rarely used in a help handler function but they are available if needed.

A few notes...

It’s up to the developer to determine what commands are performed in this function but displaying some sort of help message/document is what is expected.

While the help handler is running, the default GUI is the GUI name of the FntCFDlg window.  This allows the developer to use commands such as “gui +OwnDialogs” (to make standard dialogs (Ex: MsgBox) modal) and SB_SetText without having to change the default GUI.  If needed, the Fnt_ChooseFontDlg function will restore the default GUI to whatever it was after the add-on function returns.  This will ensure that the Fnt_ChooseFontDlg function or any add-on will not interfere with the parent script.

Note: The main FntCFDlg window will not operate correctly until the handler has completed processing so the the handler should either 1) finish quickly or 2) any dialogs displayed via the handler should be modal.  See the example scripts included with this project for an example.

Options

On input, the r_Options parameter contains the default font options.  On output, r_Options will contain the selected font options.  The following space-delimited options (in alphabetical order) are available:

boldSee the Weight section for more information.
c{color}Text color.  “{color}” is one of 16 supported color names (Ex: Blue.  See the AutoHotkey documentation for a list of possible color names), a 6-digit RGB hexadecimal color value (Ex: FF00FA), or a 6-digit hexadecimal number (Ex: 0x808080).  On input, this option will attempt to pre-select the color name.  On output, this option is returned with the selected color.  Notes and exceptions: 1) The system default text color is the default color.  On input, the default text color is pre-selected if this option is not defined.  2) If p_Effects is FALSE or does not contain the CFD_COLOR flag, this option is ignored on input and is not returned.
h{HeightInPixels}[Input Only] Font height in pixels.  Ex: h20.  See the Height section for more information.
italicOn input, this option will check the Italic option.  On output, this option will be returned if the Italic option was checked.
s{SizeInPoints}Font size in points.  For example: s12.  On input, this option will load the font size and if on the font size list, will pre-select the font size.  On output, the font size that was entered/selected is returned.
SizeMax{MaxPointSize}[Input only] Sets the maximum point size the user can enter/select.  See the Size Limits section for more information.
SizeMin{MinPointSize}[Input only] Sets the minimum point size the user can enter/select.  See the Size Limits section for more information.
strikeOn input, this option will check the Strikeout option.  On output, this option will be returned if the Strikeout option was checked.
underlineOn input, this option will check the Underline option.  On output, this option will be returned if the Underline option was checked.
w{FontWeight}Font weight (thickness or boldness), which is an integer between 1 and 1000.  Ex: w200.  See the Weight section for more information.

To specify more than one option, include a space between each option.  For example: s12 cFF0000 bold.  On output, the font options selected/set in the dialog are defined in the same format.

Owner

The p_Owner parameter is used to specify the owner of the FntCFDlg window.  Set to 0 for no owner.

For an AutoHotkey owner window, specify a valid GUI number (1-99), GUI name, or handle to the window.  When the FntCFDlg window is created, the owner window is disabled and ownership of the FntCFDlg window is assigned to the owner window.  This makes makes the FntCFDlg window modal which prevents the user from interacting with the owner window until the FntCFDlg window is closed.

For a non-AutoHotkey owner window, specify the handle to the window.  Ownership is not assigned but the window’s position and size is use to position the FntCFDlg window.

If p_Owner is not specified or is set to the handle of a non-AutoHotkey window, the AlwaysOnTop attribute is added to the FntCFDlg window to ensure that the dialog is not lost.

For all owner windows, the FntCFDlg window is positioned in the center of the owner window by default.

Size Limits

By default, the font size is not tested.  The user can enter whatever they want in most cases.  The SizeMin and SizeMax options (r_Options parameter) change that by ensuring the size is between a certain range of values.  In addition, they also limit the sizes that are shown in the Size list box.

The SizeMin{MinimumPointSize} option sets the minimum point size the user can enter/select.  Ex: SizeMin10.  If this option is specified without also specifying the SizeMax option, the SizeMax value is automatically set to the maximum point size - 0xBFFF (49151).

The SizeMax{MaximumPointSize} option sets the the maximum point size the user can enter/select.  Ex: SizeMax72.  If this option is specified without also specifying the SizeMin option, the SizeMin value is automatically set to 0.

If the user enters a font size that is outside the boundaries set by the SizeMin and SizeMax options, a MsgBox dialog is shown and the user is not allowed to continue until a valid font size is entered/selected.

Note: If the SizeMin value is greater than the SizeMax value, both size limits are invalidated and no size limits are enforced.

Status Bar

The status bar is only shown if the p_Effects parameter contains the CFD_STATUSBAR flag.  If the status bar is showing, the program will show the current font name and font options in status bar and will update it when changes are made.  The status bar is also available to the help handler.  See the example script for an example.

Weight

Weight is a font attribute that determines the thickness of the font characters.  Internally it is defined as an integer from 1 to 1000.

Most fonts support two unique weights.  The primary weight represents what the font looks like by default (i.e normal).  For most fonts, the normal/default font weight is 400.  The secondary weight represents what the font looks like when the characters are emphasized (i.e. bold).  For most fonts, the bold/heavy font weight is 700.

On input, the “bold” or “w”eight (Ex: “w600”) options defined in the r_Options variable (if any) determine if the Bold checkbox in the Style group is automatically checked or not.  If the “bold” option or a weight of 700 or more is defined (Ex: “w800”), the Bold checkbox will be checked when the dialog is shown.

On output, the actual weight of the font determines what weight options (if any) are set in the r_Options variable.  If the font weight is exactly 400, no weight options are added to the r_Options variable.  If the weight is exactly 700, “bold” is added to the r_Options variable.  If the weight is something other than 400 or 700, the “w”eight option is added to the r_Options variable with the exact weight value.  Ex: “w200”.

Programming Notes

When executed in an independent thread (Ex: Button, Click, Menu, etc.), the GUIControl commands (Hide, Show, Focus, Font, etc.) don’t work if the control’s variable name (Ex: FntCFDlg_MyEdit) is specified but they do work if the control’s handle (Ex: FntCFDlg_hMyEdit) is used.  Also note that specifying the GUI name (Ex: GUIControl FntCFDlg:Font) for these commands is superfluous when the control’s handle is specified but the GUI name remains for consistency.

Fnt_ChooseFontDlg_ChooseColor

Fnt_ChooseFontDlg_ChooseColor( hOwner,  
ByRef r_Color,  
 p_Flags: = )

Description

Creates a Color dialog box that enables the user to select a color.

Type

Used by the Fnt_ChooseFontDlg add-on.  Subject to change.  Do not call directly.

Parameters

hOwnerA handle to the window that owns the dialog box.  This parameter can be any valid window handle or it can be set to 0 or null if the dialog box has no owner.
r_ColorColor in RGB format.  [Input/Output] On input, this variable should contain the default color, i.e. the color that is initially selected when the Color dialog is displayed.  On output, this variable contains the color selected in a 6-digit hexadecimal RGB format.  Ex: 0x00FF80.  If the function returns FALSE, i.e. the Color dialog was cancelled, the value is not modified.
p_FlagsFlags used to initialize the Color dialog.  See the Flags section for the details.

Flags

The p_Flags parameter contains flags that are used to initialize and/or determine the behavior of the dialog.  If set to zero (the default) or null, the CC_FULLOPEN and CC_ANYCOLOR flags are used.  If p_Flags contains an interger value, the parameter is assumed to contain bit flags.  See the function’s static variables for a list a valid bit flags.  Otherwise, the following space-delimited text flags can be used.

AnyColorCauses the dialog box to display all available colors in the set of basic colors.
FullOpenCauses the dialog box to display the additional controls that allow the user to create custom colors.  If this flag is not set, the user must click the Define Custom Colors button to display the custom color controls.
PreventFullOpenDisables the Define Custom Colors button.

Returns

TRUE if a color was selected, otherwise FALSE which indicates that the dialog was canceled.

Fnt_ChooseFontDlg_SBSetText

Fnt_ChooseFontDlg_SBSetText(hSB,  
p_Text,  
p_PartNumber: = 1,
p_Style: = 0)

Description

Set the text in the specified part of a status bar.

Type

Used by the Fnt_ChooseFontDlg add-on.  Subject to change.  Do not call directly.

Parameters

hSBThe handle to the status bar control.
p_TextThe text to set.
p_PartNumber1-based index of the part to set.  [Optional] The default is 1.
p_StyleThe type of the drawing operation.  [Optional] The default is 0.  See the function’s static variables for a list of possible values.

Fnt_HardWordBreak

Fnt_HardWordBreak(hFont,  
p_Text,  
p_MaxW,  
p_EOL: = "`n")

Description

Inserts hard line breaks into a string of text so that the maximum width of each line is less than or equal to a specified width, in pixels.

Parameters

hFontHandle to a logical font.  Set to 0 to use the default GUI font.  See the Non-client Fonts section for additional values.
p_TextThe string to process.
p_MaxWThe maximum width of each line of text.  If the value is a simple integer (Ex: 500), the value is assumed to be in pixels.  If the value is preceded with the “c” character, the value is assumed to be in average characters of the specified font.  Ex: “c40” which is 40 average characters of the font.  If the value is preceded with the “d” character, the value is assumed to be in dialog template units of the specified font.  Ex: “d120” which is 120 dialog template units of the font.
p_EOLEnd-Of-Line (EOL) character(s) for the return string.  [Optional] See the End-Of-Line Character(s) section for more information.

Type

Experimental/Preview.  Subject to change.

Returns

A string with inserted line breaks.  Errorlevel is set to the total number of lines of text.

Calls To Other Functions

End-Of-Line Character(s)

The end-of-line (EOL) character(s) in the p_Text parameter must be in a DOS/Windows (EOL=CR+LF), Unix (EOL=LF), or DOS/Unix mix format.  A document in any other format must be converted to a DOS/Windows or Unix format before calling this function.

For the return string, the EOL character(s) are determined by the p_EOL parameter.  The default is the AutoHotkey/Unix format (EOL=LF).  This format is frequently used when setting or extracting text to/from GUI controls.

Non-client Fonts

To avoid having to temporarily create commonly used non-client fonts before calling this function, the hFont parameter can also be set to the following string values:

CaptionUse a font with the same attributes as the caption font.
MenuUse a font with the same attributes as the font used in menu bars.
Message, MsgBoxUse a font with the same attributes as the font used in message boxes.
SmCaptionUse a font with the same attributes as the small caption font.
Status, TooltipUse a font with the same attributes as the font used in status bars and tooltips.

Additional notes...

Although all non-client fonts are supported, only the fonts for non-client components that can support multiple lines, i.e. message boxes and tooltips, have any practical value for this function.

Remarks

For large documents, performance can be improved by setting SetBatchLines to a higher value before calling this function.  For example:

SetBatchLines 200ms
FormattedString:=Fnt_HardWordBreak(hFont,...)
SetBatchLines 10ms  ;-- This is the system default

Fnt_RandomFont

Fnt_RandomFont()

Description

Gets a random font.

Type

Add-on function.

Returns

Typeface name of a random font.  No fonts are excluded.

Calls To Other Functions

Fnt_RandomTTFont

Fnt_RandomTTFont()

Description

Gets a random True Type font.

Type

Add-on function.

Returns

Typeface name of a random True Type font.  OEM, symbol, and vertical fonts are excluded.

Calls To Other Functions

Remarks

This add-on function can be used as-is or it can serve as an example or template for a custom function to collect a random font.

Fnt_RandomTTFPFont

Fnt_RandomTTFPFont()

Description

Gets a random fixed pitch True Type font.

Type

Add-on function.

Returns

Typeface name of a random fixed pitch (i.e. monospaced) True Type font.  OEM, symbol, and vertical fonts are excluded.

Calls To Other Functions

Remarks

This add-on function can be used as-is or it can serve as an example or template for a custom function to collect a random font.

Fnt_RandomTTVPFont

Fnt_RandomTTVPFont()

Description

Gets a random variable pitch True Type font.

Type

Add-on function.

Returns

Typeface name of a random variable pitch (i.e. proportional) True Type font.  OEM, symbol, and vertical fonts are excluded.

Calls To Other Functions

Remarks

This add-on function can be used as-is or it can serve as an example or template for a custom function to collect a random font.

Fnt_AddFontFile(p_File,  
p_Private,  
p_Hidden: = False)
Add one or more fonts from a font file (Ex: “MySpecialFont.ttf”) to the system font table.
Fnt_CalculateSize( hFont,  
ByRef r_Text,  
 p_Options,  
ByRef r_Width: = "",
ByRef r_Height: = "")
Calculate the width and height of text.
Fnt_ChooseFont( hOwner: = 0,
ByRef r_Name: = "",
ByRef r_Options: = "",
 p_Effects: = True,
 p_Flags: = 0)
Creates and shows a Font dialog box that enables the user to choose attributes for a logical font.
Fnt_CloneFont(hFont: = "")
Creates a logical font with the same attributes as the specified logical font.
Fnt_Color2ColorName(p_Color,  
p_ConvertDefaultName: = False)
Convert a color value into one of 16 color names if a match is found.
Fnt_Color2RGB(p_Color)
Convert a color value to it’s 6-digit hexadecimal RGB value.
Fnt_ColorName2RGB(p_ColorName)
Convert a color name to it’s 6-digit hexadecimal RGB value.
Fnt_CompactPath(hFont,  
p_Path,  
p_MaxW,  
p_Strict: = False)
Shortens a file path to fit within a given pixel width by replacing path components with ellipses.
Fnt_CreateFont(p_Name: = "",
p_Options: = "")
Creates a logical font.
Fnt_CreateCaptionFont()
Creates a logical font with the same attributes as the caption font.
Fnt_CreateMenuFont()
Creates a logical font with the same attributes as the font used in menu bars.
Fnt_CreateMessageFont()
Creates a logical font with the same attributes as the font used in message boxes.
Fnt_CreatePitchAndFamilyFont(p_Pitch: = 0,
p_Family: = 0,
p_Options: = "")
Create a font by pitch and font family rather than by font name.
Fnt_CreateSmCaptionFont()
Creates a logical font with the same attributes as the small caption font.
Fnt_CreateStatusFont()
Creates a logical font with the same attributes as the font used in status bars and tooltips.
Fnt_CreateTooltipFont()
Creates a logical font with the same attributes as the font used in tooltips.
Fnt_DeleteFont(hFont)
Deletes a logical font.
Fnt_DialogTemplateUnits2Pixels( hFont,  
 p_HorzDTUs,  
 p_VertDTUs: = 0,
ByRef r_Width: = "",
ByRef r_Height: = "")
Converts dialog template units to pixels for a font.
Fnt_EnumFontFamExProc(lpelfe,
lpntme,
FontType,
p_Flags)
The default EnumFontFamiliesEx callback function for the Fnt library.
Fnt_FontExists(p_Name*)
Determines if a typeface exists on the current computer.
Fnt_FontSizeToFit(hFont,
p_String,
p_Width)
Determines the largest font size that can be used to fit a string within a specified width.
Fnt_FontSizeToFitDT(hFont,
p_String,
p_Width)
Determines the largest font size that can be used to fit a string within a specified width.
Fnt_FontSizeToFitHeight(hFont,
p_Height)
Determines the largest font size that can be used to fit within a specified height.
Fnt_FODecrementSize(ByRef r_FO,  
 p_DecrementValue: = 1,
 p_MinSize: = 1)
Decrements the value of the size option within a font options string.
Fnt_FOGetColor(p_FO,  
p_DefaultColor: = "",
p_ColorName2RGB: = False)
Get the color name or RGB color value from the color option within a font option string.
Fnt_FOGetQuality(p_FO,  
p_DefaultQuality: = 2)
Get the value of the last Quality option within a font options string.
Fnt_FOGetSize(p_FO,  
p_DefaultSize: = 0,
p_IgnoreZero: = True)
Get the size value of the last size option within a font options string.
Fnt_FOGetWeight(p_FO,  
p_DefaultWeight: = "")
Get the weight value of the last weight option within a font options string.
Fnt_FOIncrementSize(ByRef r_FO,  
 p_IncrementValue: = 1,
 p_MaxSize: = 999)
Increments the value of the size option within a font options string.
Fnt_FORemoveColor(ByRef r_FO)
Removes all color options from a font options string.
Fnt_FORemoveQuality(ByRef r_FO)
Removes all quality options from a font options string.
Fnt_FORemoveWeight(ByRef r_FO)
Removes all “w”eight and “bold” options from a font options string.
Fnt_FOSetColor(ByRef r_FO,
 p_Color)
Sets or replaces all color options within a font options string.
Fnt_FOSetQuality(ByRef r_FO,
 p_Quality)
Sets or replaces all quality options within a font options string.
Fnt_FOSetSize(ByRef r_FO,
 p_Size)
Sets or replaces all size options within a font options string.
Fnt_FOSetWeight(ByRef r_FO,
 p_Weight)
Sets or replaces all weight options within a font options string.
Fnt_GetAverageCharWidth(hFont)
Calculates the average width of characters in a font.
Fnt_GetCaptionFontName()
Returns the font name of the caption font.
Fnt_GetCaptionFontOptions()
Returns the font options of the caption font.
Fnt_GetCaptionFontSize()
Returns the point size of the caption font.
Fnt_GetBoldGUIFont()
Returns the handle to a font that has the same attributes as the default GUI font but with a weight of 700, i.e.
Fnt_GetDefaultGUIFont()
Returns the handle to the default GUI font.
Fnt_GetDefaultGUIMargins( hFont: = "",
ByRef r_MarginX: = "",
ByRef r_MarginY: = "",
 p_DPIScale: = True)
Calculates the default margins for an AutoHotkey GUI.
Fnt_GetDialogBackgroundColor()
Retrieves the current dialog background color.
Fnt_GetDialogBaseUnits( hFont: = "",
ByRef r_HorzDBUs: = "",
ByRef r_VertDBUs: = "")
Calculates the dialog base units, which are the average width and height (in pixels) of characters of a font.
Fnt_GetListOfFonts(p_CharSet: = "",
p_Name: = "",
p_Flags: = 0)
Generate a list of uniquely-named font names.
Fnt_GetLastTooltip()
Get the handle to last created tooltip control (if any).
Fnt_GetLongestString(hFont,
p_String*)
Determines the longest string (measured in pixels) from a list of strings.
Fnt_GetLongestStringDT(hFont,
p_String*)
Determines the longest string (measured in pixels) from a list of strings.
Fnt_GetFont(hControl)
Retrieves the font with which a control is currently drawing its text.
Fnt_GetFontAvgCharWidth(hFont: = "")
Retrieves the average width of characters in a font (generally defined as the width of the letter “x”).
Fnt_GetFontEmHeight(hFont: = "")
Retrieves the em height of characters in a font.
Fnt_GetFontExternalLeading(hFont: = "")
Retrieves the amount of extra leading space (if any) that an application may add between rows.
Fnt_GetFontHeight(hFont: = "")
Retrieves the cell height (ascent + descent) of characters in a font.
Fnt_GetFontInternalLeading(hFont: = "")
Retrieves the amount of leading space (if any) inside the bounds set by the tmHeight member.
Fnt_GetFontMaxCharWidth(hFont: = "")
Retrieves the width of the widest character in a font.
Fnt_GetFontMetrics(hFont: = "")
Retrieves the text metrics for a font.
Fnt_GetFontName(hFont: = "")
Retrieves the typeface name of the font.
Fnt_GetFontOptions(hFont: = "")
Retrieves the characteristics of a logical font for use in other library functions or by the AutoHotkey gui Font command.
Fnt_GetLogicalFontName(hFont)
Retrieves the typeface name of the font.
Fnt_GetLogicalFontOptions(hFont: = "")
Retrieves the attributes of a logical font in the AutoHotkey “gui Font” format.
Fnt_GetFontQuality(hFont: = "")
Get the font’s output quality.
Fnt_GetFontSize(hFont: = "")
Retrieves the point size of a font.
Fnt_GetFontWeight(hFont: = "")
Retrieves the weight (thickness or boldness) of a font.
Fnt_GetMenuFontName()
Returns the font name of the font used in menu bars.
Fnt_GetMenuFontSize()
Returns the point size of the font that is used in menu bars.
Fnt_GetMenuFontOptions()
Returns the font options of the font that is used in menu bars.
Fnt_GetMessageFontName()
Returns the font name of the font that is used in message boxes.
Fnt_GetMessageFontOptions()
Returns the font options of the font that is used in message boxes.
Fnt_GetMessageFontSize()
Returns the point size of the font that is used in message boxes.
Fnt_GetMultilineStringSize( hFont,  
 p_String,  
ByRef r_Width: = "",
ByRef r_Height: = "")
Calculates the size of a multiline string for a font.
Fnt_GetMultilineStringSizeDT( hFont,  
 p_String,  
ByRef r_Width: = "",
ByRef r_Height: = "")
Calculates the size of a multiline string for a font.
Fnt_GetNonClientMetrics()
Retrieves the metrics associated with the nonclient area of nonminimized windows.
Fnt_GetPos( hControl,  
ByRef X: = "",
ByRef Y: = "",
ByRef Width: = "",
ByRef Height: = "")
Get the position and size of a GUI control.
Fnt_GetSmCaptionFontName()
Returns the font name of the small caption font.
Fnt_GetSmCaptionFontOptions()
Returns the font options of the small caption font.
Fnt_GetSmCaptionFontSize()
Returns the point size of the small caption font.
Fnt_GetStatusFontName()
Returns the font name of the font used in status bars and tooltips.
Fnt_GetStatusFontOptions()
Returns the font options of the font that is used in status bars and tooltips.
Fnt_GetStatusFontSize()
Returns the point size of the font that is used in status bars and tooltips.
Fnt_GetTooltipFontName()
Returns the font name of the font used in tooltips.
Fnt_GetTooltipFontOptions()
Returns the font options of the font that is used in tooltips.
Fnt_GetTooltipFontSize()
Returns the point size of the font that is used in tooltips.
Fnt_GetSize( hFont,  
 p_Text,  
 p_MaxW: = 0,
ByRef r_Width: = "",
ByRef r_Height: = "")
Calculates the width and height of text that will used in a GUI control.
Fnt_GetSizeForButton( hFont,  
 p_Text,  
 p_MaxW: = 0,
ByRef r_Width: = "",
ByRef r_Height: = "")
Calculates the width and height of text that will used in a button control.
Fnt_GetSizeForEdit( hFont,  
 p_Text,  
 p_MaxW: = 0,
ByRef r_Width: = "",
ByRef r_Height: = "")
Calculates the width and height of text that will used in an Edit control.
Fnt_GetSizeForText( hFont,  
 p_Text,  
 p_MaxW: = 0,
ByRef r_Width: = "",
ByRef r_Height: = "")
Calculates the width and height of text that will used in a static control like the Text control.
Fnt_GetSizeForTextNoPrefix( hFont,  
 p_Text,  
 p_MaxW: = 0,
ByRef r_Width: = "",
ByRef r_Height: = "")
Calculates the width and height of text that will used in a static control like the Text control.
Fnt_GetStringSize( hFont,  
 p_String,  
ByRef r_Width: = "",
ByRef r_Height: = "")
Calculates the width and height (in pixels) of a string of text.
Fnt_GetStringSizeDT( hFont,  
 p_String,  
ByRef r_Width: = "",
ByRef r_Height: = "")
Calculates the width and height (in pixels) of a string of text.
Fnt_GetStringWidth(hFont,
p_String)
Calculates the width (in pixels) of a string of text.
Fnt_GetStringWidthDT(hFont,
p_String)
Calculates the width (in pixels) of a string of text.
Fnt_GetSysColor(p_DisplayElement)
Retrieves the current color of the specified display element.
Fnt_GetTabbedStringSize( hFont,  
 p_String,  
ByRef r_Width: = "",
ByRef r_Height: = "",
 p_TabStops*  )
Calculates the width and height (in pixels) of a string of text.
Fnt_GetTotalRowHeight(hFont,
p_NbrOfRows)
Calculates the height of a given number of rows of text for a font.
Fnt_GetWindowColor()
Retrieves the current window (background) color.
Fnt_GetWindowTextColor()
Retrieves the current window text color.
Fnt_HorzDTUs2Pixels(hFont,
p_HorzDTUs)
Converts horizontal dialog template units to pixels for a font.
Fnt_IsFixedPitchFont(hFont)
Determines if a font is a fixed pitch font.
Fnt_IsFont(hFont)
Determines if the hFont parameter contains the handle to valid logical font.
Fnt_IsTrueTypeFont(hFont)
Determines if a font is a TrueType font.
Fnt_Pixels2DialogTemplateUnits( hFont,  
 p_Width,  
 p_Height: = 0,
ByRef r_HorzDTUs: = "",
ByRef r_VertDTUs: = "")
Converts pixels to dialog template units for a font.
Fnt_RemoveFontFile(p_File,  
p_Private,  
p_Hidden: = False)
Remove the font(s) added with Fnt_AddFontFile.
Fnt_RGB2ColorName(p_ColorRGB,  
p_ReturnDefaultName: = False)
Convert a RGB value into one of 16 color names if a match is found.
Fnt_SetFont(hControl,  
hFont: = "",
p_Redraw: = False)
Sets the font that the control is to use when drawing text.
Fnt_SetTooltipFont(p_Name: = "",
p_Options: = "")
Creates a font and sets the last created tooltip control to use the font.
Fnt_String2DialogTemplateUnits( hFont,  
 p_String,  
ByRef r_HorzDTUs: = "",
ByRef r_VertDTUs: = "")
Converts a string to dialog template units for a font.
Fnt_String2DialogTemplateUnitsDT( hFont,  
 p_String,  
ByRef r_HorzDTUs: = "",
ByRef r_VertDTUs: = "")
Converts a string to dialog template units for a font.
Fnt_TruncateStringToFit(hFont,
p_String,
p_MaxW)
Returns a string, truncated if necessary, that is less than or equal to a specified maximum width, in pixels.
Fnt_TruncateStringWithEllipsis(hFont,
p_String,
p_MaxW)
Similar to Fnt_TruncateStringToFit except that if the string is truncated, the end of a string is replaced with an ellipses.
Fnt_TwipsPerPixel(ByRef X: = "",
ByRef Y: = "")
Determines the number of twips (abbreviation of “twentieth of an inch point”) for every pixel on the screen.
Fnt_UpdateTooltip(hTT)
Forces the tooltip to be redrawn.
Fnt_VertDTUs2Pixels(hFont,
p_VertDTUs)
Converts vertical dialog template units to pixels for a font.
Fnt_AutoFormatTabbedText(hFont,  
p_Text,  
p_TabStopSize: = 0,
p_Options = "")
Format tab-delimited text so the columns will align correctly when displayed.
Fnt_ChooseFontDlg( p_Owner: = "",
ByRef r_Name: = "",
ByRef r_Options: = "",
 p_Effects: = True,
 p_Flags: = 0,
 p_HelpHandler: = "")
An alternative to the Fnt_ChooseFont function.
Fnt_ChooseFontDlg_ChooseColor( hOwner,  
ByRef r_Color,  
 p_Flags: = )
Creates a Color dialog box that enables the user to select a color.
Fnt_ChooseFontDlg_SBSetText(hSB,  
p_Text,  
p_PartNumber: = 1,
p_Style: = 0)
Set the text in the specified part of a status bar.
Fnt_HardWordBreak(hFont,  
p_Text,  
p_MaxW,  
p_EOL: = "`n")
Inserts hard line breaks into a string of text so that the maximum width of each line is less than or equal to a specified width, in pixels.
Fnt_RandomFont()
Gets a random font.
Fnt_RandomTTFont()
Gets a random True Type font.
Fnt_RandomTTFPFont()
Gets a random fixed pitch True Type font.
Fnt_RandomTTVPFont()
Gets a random variable pitch True Type font.
For fonts used in Windows, a font family is the font or group of fonts that represent a particular typeface.
Font families describe the look of a font in a general way.
Version 3.0 of the library introduces changes to how text can be measured.
When the “r” (row) GUI option (Ex: gui Add, Text, r10) is used to determine the height of the text displayed in GUI controls that can display multiple lines of text (Button, Edit, Text, WebBrowser, etc.)
Close