# hs.styledtext

This module adds support for controlling the style of the text in Hammerspoon.

More detailed documentation is being worked on and will be provided in the Hammerspoon Wiki at https://github.com/Hammerspoon/hammerspoon/wiki. The documentation here is a condensed version provided for use within the Hammerspoon Dash docset and the inline help provided by the help console command within Hammerspoon.

The following list of attributes key-value pairs are recognized by this module and can be adjusted, set, or removed for objects by the various methods provided by this module. The list of attributes is provided here for reference; anywhere in the documentation you see a reference to the attributes key-value pairs, refer back to here for specifics:

• font - A table containing the font name and size, specified by the keys name and size. Default is the System Font at 27 points for hs.drawing text objects; otherwise the default is Helvetica at 12 points. You may also specify this as a string, which will be taken as the font named in the string at the default size, when setting this attribute.
• color - A table indicating the color of the text as described in hs.drawing.color. Default is white for hs.drawing text objects; otherwise the default is black.
• backgroundColor - Default nil, no background color (transparent).
• underlineColor - Default nil, same as color.
• strikethroughColor - Default nil, same as color.
• strokeColor - Default nil, same as color.
• strokeWidth - Default 0, no stroke; positive, stroke alone; negative, stroke and fill (a typical value for outlined text would be 3.0)
• paragraphStyle - A table containing the paragraph style. This table may contain any number of the following keys:
  • alignment - A string indicating the texts alignment. The string may contain a value of "left", "right", "center", "justified", or "natural". Default is "natural".
  • lineBreak - A string indicating how text that doesn't fit into the drawingObjects rectangle should be handled. The string may be one of "wordWrap", "charWrap", "clip", "truncateHead", "truncateTail", or "truncateMiddle". Default is "wordWrap".
  • baseWritingDirection - A string indicating the base writing direction for the lines of text. The string may be one of "natural", "leftToRight", or "rightToLeft". Default is "natural".
  • tabStops - An array of defined tab stops. Default is an array of 12 left justified tab stops 28 points apart. Each element of the array may contain the following keys:
    • location - A floating point number indicating the number of points the tab stap is located from the line's starting margin (see baseWritingDirection).
    • tabStopType - A string indicating the type of the tab stop: "left", "right", "center", or "decimal"
  • defaultTabInterval - A positive floating point number specifying the default tab stop distance in points after the last assigned stop in the tabStops field.
  • firstLineHeadIndent - A positive floating point number specifying the distance, in points, from the leading margin of a frame to the beginning of the paragraph's first line. Default 0.0.
  • headIndent - A positive floating point number specifying the distance, in points, from the leading margin of a text container to the beginning of lines other than the first. Default 0.0.
  • tailIndent - A floating point number specifying the distance, in points, from the margin of a frame to the end of lines. If positive, this value is the distance from the leading margin (for example, the left margin in left-to-right text). If 0 or negative, it's the distance from the trailing margin. Default 0.0.
  • maximumLineHeight - A positive floating point number specifying the maximum height that any line in the frame will occupy, regardless of the font size. Glyphs exceeding this height will overlap neighboring lines. A maximum height of 0 implies no line height limit. Default 0.0.
  • minimumLineHeight - A positive floating point number specifying the minimum height that any line in the frame will occupy, regardless of the font size. Default 0.0.
  • lineSpacing - A positive floating point number specifying the space in points added between lines within the paragraph (commonly known as leading). Default 0.0.
  • paragraphSpacing - A positive floating point number specifying the space added at the end of the paragraph to separate it from the following paragraph. Default 0.0.
  • paragraphSpacingBefore - A positive floating point number specifying the distance between the paragraph's top and the beginning of its text content. Default 0.0.
  • lineHeightMultiple - A positive floating point number specifying the line height multiple. The natural line height of the receiver is multiplied by this factor (if not 0) before being constrained by minimum and maximum line height. Default 0.0.
  • hyphenationFactor - The hyphenation factor, a value ranging from 0.0 to 1.0 that controls when hyphenation is attempted. By default, the value is 0.0, meaning hyphenation is off. A factor of 1.0 causes hyphenation to be attempted always.
  • tighteningFactorForTruncation - A floating point number. When the line break mode specifies truncation, the system attempts to tighten inter character spacing as an alternative to truncation, provided that the ratio of the text width to the line fragment width does not exceed 1.0 + the value of tighteningFactorForTruncation. Otherwise the text is truncated at a location determined by the line break mode. The default value is 0.05.
  • allowsTighteningForTruncation - A boolean indicating whether the system may tighten inter-character spacing before truncating text. Only available in macOS 10.11 or newer. Default true.
  • headerLevel - An integer number from 0 to 6 inclusive which specifies whether the paragraph is to be treated as a header, and at what level, for purposes of HTML generation. Defaults to 0.
• superscript - An integer indicating if the text is to be displayed as a superscript (positive) or a subscript (negative) or normal (0).
• ligature - An integer. Default 1, standard ligatures; 0, no ligatures; 2, all ligatures.
• strikethroughStyle - An integer representing the strike-through line style. See hs.styledtext.lineStyles, hs.styledtext.linePatterns and hs.styledtext.lineAppliesTo.
• underlineStyle - An integer representing the underline style. See hs.styledtext.lineStyles, hs.styledtext.linePatterns and hs.styledtext.lineAppliesTo.
• baselineOffset - A floating point value, as points offset from baseline. Default 0.0.
• kerning - A floating point value, as points by which to modify default kerning. Default nil to use default kerning specified in font file; 0.0, kerning off; non-zero, points by which to modify default kerning.
• obliqueness - A floating point value, as skew to be applied to glyphs. Default 0.0, no skew.
• expansion - A floating point value, as log of expansion factor to be applied to glyphs. Default 0.0, no expansion.
• shadow - Default nil, indicating no drop shadow. A table describing the drop shadow effect for the text. The table may contain any of the following keys:
  • offset - A table with h and w keys (a size structure) which specify horizontal and vertical offsets respectively for the shadow. Positive values always extend down and to the right from the user's perspective.
  • blurRadius - A floating point value specifying the shadow's blur radius. A value of 0 indicates no blur, while larger values produce correspondingly larger blurring. The default value is 0.
  • color - The default shadow color is black with an alpha of 1/3. If you set this property to nil, the shadow is not drawn.

To make the hs.styledtext objects easier to use, in addition to the module specific functions and methods defined, some of the Lua String library has been reproduced to perform similar functions on these objects. See the help section for each method for more information on their use:

• hs.styledtext:byte
• hs.styledtext:find
• hs.styledtext:gmatch
• hs.styledtext:len
• hs.styledtext:lower
• hs.styledtext:match
• hs.styledtext:rep
• hs.styledtext:sub
• hs.styledtext:upper

In addition, the following metamethods have been included:

• concat:
  • string..object yields the string values concatenated
  • object..string yields a new hs.styledtext object with string appended
  • two hs.styledtext objects yields a new hs.styledtext object containing the concatenation of the two objects
• len: #object yields the length of the text contained in the object
• eq: object ==/~= object yields a boolean indicating if the text of the two objects is equal or not. Use hs.styledtext:isIdentical if you need to compare attributes as well.
• lt, le: allows <, >, <=, and >= comparisons between objects and strings in which the text of an object is compared with the text of another or a Lua string.

Note that due to differences in the way Lua determines when to use metamethods for equality comparisons versus relative-position comparisons, ==/_{= cannot compare an object to a Lua string (it will always return false because the types are different). You must use object:getString() ==/}= string. (see hs.styledtext:getString)

---

# API Overview

Constants - Useful values which cannot be changed

• defaultFonts
• fontTraits
• lineAppliesTo
• linePatterns
• lineStyles

Functions - API calls offered directly by the extension

• convertFont
• fontFamilies
• fontInfo
• fontNames
• fontNamesWithTraits
• fontPath
• fontsForFamily
• loadFont
• validFont

Constructors - API calls which return an object, typically one that offers API methods

• ansi
• getStyledTextFromData
• getStyledTextFromFile
• new

Methods - API calls which can only be made on an object returned by a constructor

• asTable
• byte
• convert
• copy
• find
• getString
• gmatch
• isIdentical
• len
• lower
• match
• removeStyle
• rep
• setString
• setStyle
• sub
• upper

---

# API Documentation

# Constants

# defaultFonts

---

# fontTraits

---

# lineAppliesTo

---

# linePatterns

---

# lineStyles

---

# Functions

# convertFont

| | | | --------------------------------------------|-------------------------------------------------------------------------------------| | Signature | hs.styledtext.convertFont(fontTable, trait) -> table | | Type | Function | | Description | Returns the font which most closely matches the given font and the trait change requested. | | Parameters |

• font - a string or a table which specifies a font. If a string is given, the default system font size is assumed. If a table is provided, it should contain the following keys: name - the name of the font (defaults to the system font) size - the point size of the font (defaults to the default system font size)
• trait - a number corresponding to a trait listed in hs.styledtext.fontTraits you wish to add or remove (unboldFont and unitalicFont) from the given font, or a boolean indicating whether you want a heavier version (true) or a lighter version (false).

| | Returns |

• a table containing the name and size of the font which most closely matches the specified font and the trait change requested. If no such font is available, then the original font is returned unchanged.

| | Notes | None | | Examples | None | | Source | extensions/styledtext/libstyledtext.m line 305 |

---

# fontFamilies

---

# fontInfo

| | | | --------------------------------------------|-------------------------------------------------------------------------------------| | Signature | hs.styledtext.fontInfo(font) -> table | | Type | Function | | Description | Get information about the font Specified in the attributes table. | | Parameters |

• font - a string or a table which specifies a font. If a string is given, the default system font size is assumed. If a table is provided, it should contain the following keys: name - the name of the font (defaults to the system font) size - the point size of the font (defaults to the default system font size)

| | Returns |

• a table containing the following keys:
• fontName - The font's internally recognized name.
• familyName - The font's family name.
• displayName - The font’s display name is typically localized for the user’s language.
• fixedPitch - A boolean value indicating whether all glyphs in the font have the same advancement.
• ascender - The top y-coordinate, offset from the baseline, of the font’s longest ascender.
• boundingRect - A table containing the font’s bounding rectangle, scaled to the font’s size. This rectangle is the union of the bounding rectangles of every glyph in the font.
• capHeight - The cap height of the font.
• descender - The bottom y-coordinate, offset from the baseline, of the font’s longest descender.
• italicAngle - The number of degrees that the font is slanted counterclockwise from the vertical. (read-only)
• leading - The leading value of the font.
• maximumAdvancement - A table containing the maximum advance of any of the font’s glyphs.
• numberOfGlyphs - The number of glyphs in the font.
• pointSize - The point size of the font.
• underlinePosition - The baseline offset to use when drawing underlines with the font.
• underlineThickness - The thickness to use when drawing underlines with the font.
• xHeight - The x-height of the font.

| | Notes | None | | Examples | None | | Source | extensions/styledtext/libstyledtext.m line 449 |

---

# fontNames

---

# fontNamesWithTraits

---

# fontPath

---

# fontsForFamily

---

# loadFont

---

# validFont

---

# Constructors

# ansi

---

# getStyledTextFromData

| | | | --------------------------------------------|-------------------------------------------------------------------------------------| | Signature | hs.styledtext.getStyledTextFromData(data, [type]) -> styledText object | | Type | Constructor | | Description | Converts the provided data into a styled text string. | | Parameters |

• data - the data, as a lua string, which contains the raw data to be converted to a styledText object
• type - a string indicating the format of the contents in data. Defaults to "html". The string may be one of the following (not all formats may be fully representable as a simple string container - see also hs.styledtext.setTextFromFile): "text" - Plain text document. "rtf" - Rich text format document. "rtfd" - Rich text format with attachments document. "simpleText" - Macintosh SimpleText document. "html" - Hypertext Markup Language (HTML) document. "word" - Microsoft Word document. "wordXML" - Microsoft Word XML (WordML schema) document. "webArchive" - Web Kit WebArchive document. "openXML" - ECMA Office Open XML text document format. "open" - OASIS Open Document text document format.

| | Returns |

• the styledText object

| | Notes |

• See also hs.styledtext.getStyledTextFromFile

| | Examples | None | | Source | extensions/styledtext/libstyledtext.m line 96 |

---

# getStyledTextFromFile

| | | | --------------------------------------------|-------------------------------------------------------------------------------------| | Signature | hs.styledtext.getStyledTextFromFile(file, [type]) -> styledText object | | Type | Constructor | | Description | Converts the data in the specified file into a styled text string. | | Parameters |

• file - the path to the file to use as the source for the data to convert into a styledText object
• type - a string indicating the format of the contents in data. Defaults to "html". The string may be one of the following (not all formats may be fully representable as a simple string container - see also hs.styledtext.setTextFromFile): "text" - Plain text document. "rtf" - Rich text format document. "rtfd" - Rich text format with attachments document. "simpleText" - Macintosh SimpleText document. "html" - Hypertext Markup Language (HTML) document. "word" - Microsoft Word document. "wordXML" - Microsoft Word XML (WordML schema) document. "webArchive" - Web Kit WebArchive document. "openXML" - ECMA Office Open XML text document format. "open" - OASIS Open Document text document format.

| | Returns |

• the styledText object

| | Notes |

• See also hs.styledtext.getStyledTextFromData

| | Examples | None | | Source | extensions/styledtext/libstyledtext.m line 174 |

---

# new

---

# Methods

# asTable

---

# byte

---

# convert

| | | | --------------------------------------------|-------------------------------------------------------------------------------------| | Signature | hs.styledtext:convert([type]) -> string | | Type | Method | | Description | Converts the styledtext object into the data format specified. | | Parameters |

• type - a string indicating the format to convert the styletext object into. Defaults to "html". The string may be one of the following: "text" - Plain text document. "rtf" - Rich text format document. "rtfd" - Rich text format with attachments document. "html" - Hypertext Markup Language (HTML) document. "word" - Microsoft Word document. "wordXML" - Microsoft Word XML (WordML schema) document. "webArchive" - Web Kit WebArchive document. "openXML" - ECMA Office Open XML text document format. "open" - OASIS Open Document text document format.

| | Returns |

• a string containing the converted data

| | Notes | None | | Examples | None | | Source | extensions/styledtext/libstyledtext.m line 1216 |

---

# copy

---

# find

---

# getString

---

# gmatch

---

# isIdentical

---

# len

---

# lower

---

# match

---

# removeStyle

---

# rep

---

# setString

---

# setStyle

---

# sub

---

# upper

---

---