FontVariation
A variant of a shared font: axes, synthetic style, spacing and color palette.
FontVariation references BaseFont and supplies separate style settings. It neither clones the font file nor represents an Entity. Several variants can share one FontFile; editing that shared base can affect all variants. Assign the base explicitly for reproducible exports. Without BaseFont, use resolves a theme/fallback font; GetBaseFont can still return null. Avoid cyclic BaseFont chains.
VariationOpentype selects variable-font axes; OpentypeFeatures selects shaping features such as ligatures. These are separate tables. First obtain available axes and ranges through BaseFont.GetSupportedVariationList. For weight use the numeric key returned by TextServerManager.GetPrimaryInterface().NameToTag("wght"). In 1.0.0 the string "wght" can be stored in a Dictionary yet fail to distinguish the variant from the default during cache matching. A numeric tag or supported canonical name avoids this ambiguity. Adding an axis to a static font does not create a genuine new face.
VariationOpentype and OpentypeFeatures copy their flat Dictionary on both assignment and reading. Editing a returned table does not change the resource: assign it back. This differs from low-level FontFile.GetVariationCoordinates and GetOpentypeFeatureOverrides, which return shared tables. Changed FontVariation settings invalidate its caches and emit Changed; repeating the same value normally does not. Direct FontFile cache edits do not emit Changed.
VariationEmbolden and VariationTransform synthesize outlines rather than replacing a designed bold/italic face. SpacingTop/Bottom/Space/Glyph add pixels; BaselineOffset is a fraction of font height. None sets the Control font_size. Check wrapping, clipping and line height after edits.
PaletteIndex and PaletteCustomColors require a font/backend with supported color palettes. Index 0 selects the first palette; transparent Color(0,0,0,0) entries retain corresponding original colors. Managed color arrays are copied; assign edits back. Palette settings neither color an ordinary monochrome font nor establish color-emoji support.
Declarations checked against C# SDK 1.0.0. Expand a name to see declarations and documentation.
Constructors1
FontVariationConstructor
public FontVariation();Creates a variant without explicit BaseFont: empty axes/features, zero spacing/emboldening, Identity transform and palette 0. Assign BaseFont for predictable results.
Properties13
BaseFontProperty
public Font BaseFont { get; set; }Shared base Font reference rather than a file copy. null resolves a theme/fallback when used, but the getter need not return that resolved font. Changing the base invalidates the variant; avoid cycles.
BaselineOffsetProperty
public float BaselineOffset { get; set; }Extra baseline offset as a fraction of font height, default 0. Not pixels; check clipping and alignment after changing it.
OpentypeFeaturesProperty
public Reckfell.Collections.Dictionary OpentypeFeatures { get; set; }Shaping features such as liga/kern with integer values rather than axis coordinates. Setter/getter copy Dictionary. An entry does not establish font support; assign an edited copy back.
PaletteCustomColorsProperty
public Color[] PaletteCustomColors { get; set; }Replacement palette colors. Color(0,0,0,0) retains the original entry. C# copies input and getter results; assign edited arrays back. Requires a supported color font.
PaletteIndexProperty
public long PaletteIndex { get; set; }Supported color-palette index starting at 0. Check the font/backend GetPaletteCount. Stored values do not establish visual support.
SpacingBottomProperty
public int SpacingBottom { get; set; }Extra spacing below a line in pixels, default 0. Not a scale for the whole font.
SpacingGlyphProperty
public int SpacingGlyph { get; set; }Extra spacing between graphical glyphs in pixels, default 0. Not a scale for the whole font.
SpacingSpaceProperty
public int SpacingSpace { get; set; }Extra spacing to a space advance in pixels, default 0. Not a scale for the whole font.
SpacingTopProperty
public int SpacingTop { get; set; }Extra spacing above a line in pixels, default 0. Not a scale for the whole font.
VariationEmboldenProperty
public float VariationEmbolden { get; set; }Synthetic embolden strength, 0 unchanged. Positive values thicken outlines, negative values thin them; not genuine face weight.
VariationFaceIndexProperty
public int VariationFaceIndex { get; set; }Collection face index, default 0. Choose an existing face; setter storage alone does not establish availability in the file. Not an axis or RID-cache index.
VariationOpentypeProperty
public Reckfell.Collections.Dictionary VariationOpentype { get; set; }Variable-font axis coordinates. Use numeric NameToTag keys and GetSupportedVariationList ranges: the raw string "wght" can fail to change the selected cache in 1.0.0. Setter/getter copy the table; assign edited copies back. Separate from liga/kern.
VariationTransformProperty
public Transform2D VariationTransform { get; set; }Outline transform, Identity by default. Suitable for synthetic slant/rotation rather than the Control Transform or a designed italic face.
Methods19
GetBaseFontFont
public Font GetBaseFont();Shared base Font reference rather than a file copy. null resolves a theme/fallback when used, but the getter need not return that resolved font. Changing the base invalidates the variant; avoid cycles.
FontShared explicitly assigned Font reference or null rather than a copy.
GetBaselineOffsetfloat
public float GetBaselineOffset();Extra baseline offset as a fraction of font height, default 0. Not pixels; check clipping and alignment after changing it.
floatCurrent stored value rather than visual-result validation.
GetPaletteCustomColorsColor[]
public Color[] GetPaletteCustomColors();Replacement palette colors. Color(0,0,0,0) retains the original entry. C# copies input and getter results; assign edited arrays back. Requires a supported color font.
Color[]New Color[]; editing the result does not change the resource.
GetPaletteIndexlong
public long GetPaletteIndex();Supported color-palette index starting at 0. Check the font/backend GetPaletteCount. Stored values do not establish visual support.
longCurrent stored value rather than visual-result validation.
GetVariationEmboldenfloat
public float GetVariationEmbolden();Synthetic embolden strength, 0 unchanged. Positive values thicken outlines, negative values thin them; not genuine face weight.
floatCurrent stored value rather than visual-result validation.
GetVariationFaceIndexint
public int GetVariationFaceIndex();Collection face index, default 0. Choose an existing face; setter storage alone does not establish availability in the file. Not an axis or RID-cache index.
intCurrent stored value rather than visual-result validation.
GetVariationOpentypeReckfell.Collections.Dictionary
public Reckfell.Collections.Dictionary GetVariationOpentype();Variable-font axis coordinates. Use numeric NameToTag keys and GetSupportedVariationList ranges: the raw string "wght" can fail to change the selected cache in 1.0.0. Setter/getter copy the table; assign edited copies back. Separate from liga/kern.
Reckfell.Collections.DictionaryNew flat coordinate Dictionary; assign an edited table back.
GetVariationTransformTransform2D
public Transform2D GetVariationTransform();Outline transform, Identity by default. Suitable for synthetic slant/rotation rather than the Control Transform or a designed italic face.
Transform2DCurrent stored value rather than visual-result validation.
SetBaseFontvoid
public void SetBaseFont(Font font);Shared base Font reference rather than a file copy. null resolves a theme/fallback when used, but the getter need not return that resolved font. Changing the base invalidates the variant; avoid cycles. A changed value emits Changed; the same value does not.
| Name | Type | Default |
|---|---|---|
font | Font | — |
fontShared Font, or null for theme/fallback resolution; avoid BaseFont cycles.
SetBaselineOffsetvoid
public void SetBaselineOffset(float baselineOffset);Extra baseline offset as a fraction of font height, default 0. Not pixels; check clipping and alignment after changing it. A changed value emits Changed; the same value does not.
| Name | Type | Default |
|---|---|---|
baselineOffset | float | — |
baselineOffsetFinite fraction of font height, 0 without an extra offset.
SetOpentypeFeaturesvoid
public void SetOpentypeFeatures(Reckfell.Collections.Dictionary features);Shaping features such as liga/kern with integer values rather than axis coordinates. Setter/getter copy Dictionary. An entry does not establish font support; assign an edited copy back. A changed value emits Changed; the same value does not.
| Name | Type | Default |
|---|---|---|
features | Reckfell.Collections.Dictionary | — |
featuresFlat Dictionary mapping OpenType features to integer values. Setter copies it.
SetPaletteCustomColors2 overloads
public void SetPaletteCustomColors(Color[] colors);Replacement palette colors. Color(0,0,0,0) retains the original entry. C# copies input and getter results; assign edited arrays back. Requires a supported color font. A changed value emits Changed; the same value does not.
| Name | Type | Default |
|---|---|---|
colors | Color[] | — |
colorsColors by palette-entry index; a transparent entry retains the original color. Input is copied.
public void SetPaletteCustomColors(ReadOnlySpan<Color> colors);Replacement palette colors. Color(0,0,0,0) retains the original entry. C# copies input and getter results; assign edited arrays back. Requires a supported color font. A changed value emits Changed; the same value does not.
| Name | Type | Default |
|---|---|---|
colors | ReadOnlySpan<Color> | — |
colorsColors by palette-entry index; a transparent entry retains the original color. Input is copied.
SetPaletteIndexvoid
public void SetPaletteIndex(long paletteIndex);Supported color-palette index starting at 0. Check the font/backend GetPaletteCount. Stored values do not establish visual support. A changed value emits Changed; the same value does not.
| Name | Type | Default |
|---|---|---|
paletteIndex | long | — |
paletteIndexNonnegative index of an existing font palette; 0 selects the first.
SetSpacingvoid
public void SetSpacing(TextServer.SpacingType spacing, int value);Sets extra pixels for Glyph, Space, Top or Bottom. Neither a font_size percentage nor pair kerning. Changes invalidate the variant cache and emit Changed.
| Name | Type | Default |
|---|---|---|
spacing | TextServer.SpacingType | — |
value | int | — |
spacingGlyph, Space, Top or Bottom from TextServer.SpacingType.
valueExtra integer pixels; negative values can cause overlap.
SetVariationEmboldenvoid
public void SetVariationEmbolden(float strength);Synthetic embolden strength, 0 unchanged. Positive values thicken outlines, negative values thin them; not genuine face weight. A changed value emits Changed; the same value does not.
| Name | Type | Default |
|---|---|---|
strength | float | — |
strengthFinite synthetic embolden strength; 0 unchanged.
SetVariationFaceIndexvoid
public void SetVariationFaceIndex(int faceIndex);Collection face index, default 0. Choose an existing face; setter storage alone does not establish availability in the file. Not an axis or RID-cache index. A changed value emits Changed; the same value does not.
| Name | Type | Default |
|---|---|---|
faceIndex | int | — |
faceIndexExisting collection face index, usually 0. Do not pass negative/nonexistent indices.
SetVariationOpentypevoid
public void SetVariationOpentype(Reckfell.Collections.Dictionary coords);Variable-font axis coordinates. Use numeric NameToTag keys and GetSupportedVariationList ranges: the raw string "wght" can fail to change the selected cache in 1.0.0. Setter/getter copy the table; assign edited copies back. Separate from liga/kern. A changed value emits Changed; the same value does not.
| Name | Type | Default |
|---|---|---|
coords | Reckfell.Collections.Dictionary | — |
coordsFlat Dictionary mapping numeric axis tags to numbers; obtain tags through NameToTag and ranges from the font.
SetVariationTransformvoid
public void SetVariationTransform(Transform2D transform);Outline transform, Identity by default. Suitable for synthetic slant/rotation rather than the Control Transform or a designed italic face. A changed value emits Changed; the same value does not.
| Name | Type | Default |
|---|---|---|
transform | Transform2D | — |
transformFinite outline matrix; Identity unchanged.