pix 0.9: Reference Manual

::pix::fontTop, Main, Index

Enum HorizontalAlignment:Top, Main, Index

Enum VerticalAlignment:Top, Main, Index

CommandsTop, Main, Index

ascent [::pix::font]Top, Main, Index

Gets the font ascender value in font units.

ascent typeface
Parameters
typefacefont::readTypeface
Description

The ascender is the distance from the baseline to the highest point of any glyph.

Return value

A double value in pixels (always positive).

capHeight [::pix::font]Top, Main, Index

The font cap height value in font units (pixie >= 5.1.0).

capHeight typeface
Parameters
typefacefont::readTypeface
Description

The cap height is the distance from the baseline to the highest point of any glyph in the font. This value is used to position text in the y-direction.

Return value

A value is in pixels but can be a floating point value.

color [::pix::font]Top, Main, Index

Sets the font color (Equivalent to pix::font::configure).

color font color
Parameters
fontfont::readFont object handle
colorcolor string (e.g., "red" or "#HEX")
Return value

Nothing.

computeBounds [::pix::font]Top, Main, Index

Computes the bounding box of a text arrangement.

computeBounds arrangement ?transform?
Parameters
arrangementfont::typeset object (from pix::font::typeset)
transformoptional 3x3 transformation matrix Optional, default identityMatrix.
Description

The bounds represent the axis-aligned bounding box of all filled glyph regions in the arrangement's coordinate system.

Return value

A Tcl dict value where:

x The x offset of the top-left corner of the bounds.
y The y offset of the top-left corner of the bounds.
w The width of the bounds.
h The height of the bounds.

configure [::pix::font]Top, Main, Index

Configure font::readFont parameters.

configure font options
Parameters
fontfont::readFont
optionsA Tcl dict, see description below.
Description

noKerningAdjustments Boolean.
underline Boolean.
strikethrough Boolean.
size Double (pixels).
lineHeight Double (pixels).
color Color string.
paint paint object.
Return value

Nothing.

copy [::pix::font]Top, Main, Index

Copy font.

copy font
Parameters
fontfont::readFont
Return value

A new handle font object.

defaultLineHeight [::pix::font]Top, Main, Index

The default line height in pixels for the current font size.

defaultLineHeight font
Parameters
fontfont::readFont
Description

This proc calculates and returns the default line height of the font in pixels, based on its current size and other internal properties. The line height is used to determine the vertical distance between the baselines of two lines of text.

For example, if the line height is 15.0, then the baseline of the second line of text will be 15.0 pixels below the baseline of the first line of text.

Return value

The line height is in pixels.

descent [::pix::font]Top, Main, Index

Gets the font descender value in font units.

descent typeface
Parameters
typefacefont::readTypeface
Description

The descent is the distance from the baseline to the lowest point of any glyph.

Return value

A double value in pixels (usually negative).

destroy [::pix::font]Top, Main, Index

Destroy the font or all fonts if special word all is specified.

destroy value
Parameters
valuefont::readFont or string
Return value

Nothing.

destroyTface [::pix::font]Top, Main, Index

Destroy the font::readTypeface or all typefaces if special word all is specified.

destroyTface value
Parameters
valuefont::readTypeface or string
Return value

Nothing.

fallbackTypeface [::pix::font]Top, Main, Index

Searches through fallback typefaces to find one containing the specified character.

fallbackTypeface typeface char
Parameters
typefacefont::readTypeface object handle.
charthe character to look for.
Return value

A handle to the fallback typeface, or the original typeface if it already contains the glyph.

getAdvance [::pix::font]Top, Main, Index

Try to get the advance width for the given rune in pixels. If the rune is not supported by the typeface, this will raise an exception.

getAdvance typeface char
Parameters
typefacefont::readTypeface
charchar
Return value

A value is in pixels

getGlyphPath [::pix::font]Top, Main, Index

The glyph path for the rune.

getGlyphPath typeface char
Parameters
typefacefont::readTypeface
charchar
Return value

A new handle path object.

getKerningAdjustment [::pix::font]Top, Main, Index

Retrieve the kerning adjustment for the pair of characters (c1, c2) from the typeface.

getKerningAdjustment typeface char1 char2
Parameters
typefacefont::readTypeface
char1char
char2char
Description

Kerning is the process of adjusting the space between characters in a proportional font. The kerning adjustment is measured in pixels and is specific to the pair of characters. This allows for more visually pleasing and readable text by reducing or increasing space between specific pairs of characters, depending on the typeface design.

Return value

A Tcl double value.

hasGlyph [::pix::font]Top, Main, Index

Guess if the glyph exists for this rune.

hasGlyph typeface char
Parameters
typefacefont::readTypeface
charchar
Return value

A Tcl boolean value.

layoutBounds [::pix::font]Top, Main, Index

Computes the logical width and height (in pixels) of the given object.

layoutBounds object text
Parameters
objecttypeset, readFont or newSpan object.
textrequired only if a font object is provided.
Return value

A Tcl list {width height}.

lineGap [::pix::font]Top, Main, Index

Gets the font line gap value in font units.

lineGap typeface
Parameters
typefacefont::readTypeface
Description

The line gap is the distance in font units between the baseline of one line of text and the baseline of the next. The line gap is used to determine the spacing between lines of text.

Return value

The line gap value in font units.

lineHeight [::pix::font]Top, Main, Index

The default line height in font units.

lineHeight typeface
Parameters
typefacefont::readTypeface
Description

The line height is the height of a line of text in the font, which is typically slightly larger than the ascent of the font (the height above the baseline) plus the descent of the font (the height below the baseline).

The line height is typically used to determine the vertical distance between the baselines of two lines of text.

Return value

A Tcl double value.

name [::pix::font]Top, Main, Index

This procedure retrieves the name of a given typeface object.

name typeface
Parameters
typefacefont::readTypeface
Return value

The name of the font.

newFont [::pix::font]Top, Main, Index

Creates a new font object from a given TypeFace.

newFont typeface
Parameters
typefacereadTypeface object handle (created via pix::font::readTypeface)
Return value

A new handle font object.

newSpan [::pix::font]Top, Main, Index

Sets new Span.

newSpan font text
Parameters
fontfont::readFont
textstring
Return value

A new handle object.

paint [::pix::font]Top, Main, Index

Sets font Paint if paint optional argument is set, otherwise gets the font paint.

paint font ?paint?
Parameters
fontfont::readFont
paintpaint Optional, default "".
Return value

A new handle paint object if no paint optional argument is set, otherwise set the font paint.

parseOtf [::pix::font]Top, Main, Index

Parse Otf string.

parseOtf buffer
Parameters
bufferstring
Description

The goal is to take a string buffer containing an Otf (Open Type Font) and parse it into a TypeFace object.

Return value

A new handle object.

parseSvgFont [::pix::font]Top, Main, Index

Parse Svg Font string.

parseSvgFont buffer
Parameters
bufferstring
Description

The pix::font::parseSvgFont function is used to interpret the string as an SVG font and convert it into a TypeFace object.

Return value

A new handle object.

parseTtf [::pix::font]Top, Main, Index

Parse Ttf string.

parseTtf buffer
Parameters
bufferstring
Description

The pix::font::parseTtf function is used to interpret the string as a Ttf (TrueType Font) and convert it into a TypeFace object.

Return value

A new handle object.

readFont [::pix::font]Top, Main, Index

Attempts to read a font from the specified file path.

readFont filePath
Parameters
filePathpath to the font file.
Description

Pixie handles font loading and verification. If the file does not exist or is invalid, an error message is returned.

Return value

A new handle font object.

readTypeface [::pix::font]Top, Main, Index

Loads a typeface from a file.

readTypeface filePath
Parameters
filePathfile font (otf, ttc, ttf, svg)
Return value

A new handle object.

See also

font::parseTtf, font::parseOtf, font::parseSvgFont

readTypefaces [::pix::font]Top, Main, Index

Loads a OpenType Collection (.ttc).

readTypefaces filePath
Parameters
filePathfile font (ttc)
Return value

A Tcl list with Typeface objects.

scale [::pix::font]Top, Main, Index

The scale factor to transform font units into pixels.

scale object
Parameters
objectfont::readFont or font::readTypeface object.
Return value

A Tcl double value.

selectionRects [::pix::font]Top, Main, Index

Gets the selection rectangles for a text arrangement.

selectionRects arrangement
Parameters
arrangementfont::typeset object handle.
Return value

A Tcl dictionary where each value represents a selection rectangle {x y w h}.

size [::pix::font]Top, Main, Index

Sets the font size (Equivalent to pix::font::configure).

size font size
Parameters
fontfont object handle
sizeDouble value (in pixels)
Return value

Nothing.

typeset [::pix::font]Top, Main, Index

Lays out the character glyphs and returns the arrangement.

typeset object ?options?
Parameters
objectfont::readFont or font::newSpan
optionsA Tcl dict, see description below. Optional, default "".
Description

bounds A list coordinates.
hAlign A Enum value.
vAlign A Enum value.
wrap A boolean value.
Return value

A new handle object.