Class TCastleFont

Description
Hierarchy
Constants
Methods
Properties

Unit

CastleFonts

Declaration

type TCastleFont = class(TCastleAbstractFont)

Description

Font loaded from a font file, like ttf or otf. This class is typically used for outline (scalable, vector) fonts in ttf or otf formats. But it can really deal with any font supported by the FreeType library, even bitmap fonts, see the summary of font formats supported by FreeType.

This can load a font file, or it can use ready data in TTextureFontData. The latter allows to use this for fonts embedded in a Pascal source code, since our texture-font-to-pascal can convert a font file to a unit that defines ready TTextureFontData instance.

Source: fonts/castlefonts_font.inc (line 30).

Hierarchy

Show Additional Members:

Overview

Constants

Public DefaultMeasureHeight = 'AOHIypq';
Public DefaultMeasureCapHeight = 'HI';
Public DefaultMeasureDescenderHeight = 'ya';
Public DefaultOptimalSize = 20;

Methods

Protected function GetInternalText: String; virtual;
Protected procedure SetInternalText(const Value: String); virtual;
Protected procedure SetName(const Value: TComponentName); override;
Protected procedure TranslateProperties(const TranslatePropertyEvent: TTranslatePropertyEvent); virtual;
Public procedure CustomSerialization(const SerializationProcess: TSerializationProcess); virtual;
Public procedure SetTransient;
Public procedure AddNonVisualComponent(const NonVisualComponent: TComponent);
Public procedure InsertNonVisualComponent(const Index: Integer; const NonVisualComponent: TComponent);
Public procedure RemoveNonVisualComponent(const NonVisualComponent: TComponent);
Public function NonVisualComponentsIndexOf(const NonVisualComponent: TComponent): Integer;
Public function NonVisualComponentsCount: Integer;
Public function NonVisualComponentsEnumerate: TNonVisualComponentsEnumerator;
Public function ValueIsStreamed: Boolean; virtual;
Public procedure DesignerInfo(const SList: TStrings); virtual;
Public procedure DesignerWarnings(const SList: TStrings); virtual;
Public procedure PrintAndMove(const s: string); deprecated 'use Print(X, Y, ...), and move the (X, Y) yourself based on TextMove, instead of this';
Public procedure Print(const X, Y: Single; const Color: TCastleColor; const S: string); overload; virtual; abstract;
Public procedure Print(const Pos: TVector2Integer; const Color: TCastleColor; const S: string); overload;
Public procedure Print(const Pos: TVector2; const Color: TCastleColor; const S: string); overload;
Public procedure Print(const X, Y: Single; const S: string); overload; deprecated 'instead of this, use Print overload that takes explicit X,Y,Color parameters';
Public procedure Print(const s: string); overload; deprecated 'instead of this, use Print overload that takes explicit X,Y,Color parameters';
Public procedure PrintRect(const Rect: TRectangle; const Color: TCastleColor; const S: string; const HorizontalAlignment: THorizontalPosition; const VerticalAlignment: TVerticalPosition); overload;
Public procedure PrintRect(const Rect: TFloatRectangle; const Color: TCastleColor; const S: string; const HorizontalAlignment: THorizontalPosition; const VerticalAlignment: TVerticalPosition); overload;
Public procedure PrintRectMultiline(const Rect: TRectangle; const Color: TCastleColor; const S: string; const HorizontalAlignment: THorizontalPosition; const VerticalAlignment: TVerticalPosition; const Html: boolean; const LineSpacing: Integer; const TextHorizontalAlignment: THorizontalPosition = hpLeft); overload;
Public procedure PrintRectMultiline(const Rect: TFloatRectangle; const Color: TCastleColor; const S: string; const HorizontalAlignment: THorizontalPosition; const VerticalAlignment: TVerticalPosition; const Html: boolean; const LineSpacing: Integer; const TextHorizontalAlignment: THorizontalPosition = hpLeft); overload;
Public function TextWidth(const S: string): Single; virtual; abstract;
Public function TextHeight(const S: string): Single; virtual; abstract;
Public function TextHeightBase(const S: string): Single; virtual; abstract;
Public function TextMove(const S: string): TVector2; virtual; abstract;
Public function TextSize(const S: string): TVector2;
Public function RowHeight: Single; deprecated 'use Height';
Public function RowHeightBase: Single; deprecated 'use CapHeight';
Public function Descend: Single; deprecated 'use DescenderHeight';
Public function Height: Single;
Public function CapHeight: Single;
Public function DescenderHeight: Single;
Public procedure BreakLines(const unbroken: string; broken: TStrings; MaxLineWidth: Single); overload;
Public procedure BreakLines(unbroken, broken: TStrings; MaxLineWidth: Single); overload;
Public procedure BreakLines(broken: TStrings; MaxLineWidth: Single; FirstToBreak: integer); overload;
Public function MaxTextWidth(SList: TStrings; const Html: boolean = false): Single;
Public procedure PrintStrings(const X0, Y0: Single; const Color: TCastleColor; const Strs: TStrings; const Html: boolean; const LineSpacing: Single; const TextHorizontalAlignment: THorizontalPosition = hpLeft); overload;
Public procedure PrintStrings(const X0, Y0: Single; const Color: TCastleColor; const Strs: array of string; const Html: boolean; const LineSpacing: Single; const TextHorizontalAlignment: THorizontalPosition = hpLeft); overload;
Public procedure PrintStrings(const Strs: TStrings; const Html: boolean; const LineSpacing: Single; const X0: Single = 0; const Y0: Single = 0); overload; deprecated 'instead of this, use PrintStrings version that takes explicit Color parameter';
Public procedure PrintStrings(const Strs: array of string; const Html: boolean; const LineSpacing: Single; const X0: Single = 0; const Y0: Single = 0); overload; deprecated 'instead of this, use PrintStrings version that takes explicit Color parameter';
Public function PrintBrokenString(const Rect: TRectangle; const Color: TCastleColor; const S: string; const LineSpacing: Single; const AlignHorizontal: THorizontalPosition; const AlignVertical: TVerticalPosition; const Html: boolean = false): Integer; overload;
Public function PrintBrokenString(const Rect: TFloatRectangle; const Color: TCastleColor; const S: string; const LineSpacing: Single; const AlignHorizontal: THorizontalPosition; const AlignVertical: TVerticalPosition; const Html: boolean = false): Integer; overload;
Public function PrintBrokenString(X0, Y0: Single; const Color: TCastleColor; const S: string; const MaxLineWidth: Single; const PositionsFirst: boolean; const LineSpacing: Single; const Html: boolean = false): Integer; overload;
Public function PrintBrokenString(const S: string; const MaxLineWidth, X0, Y0: Single; const PositionsFirst: boolean; const LineSpacing: Single): Integer; overload; deprecated 'instead of this, use PrintBrokenString that takes explicit Color parameter';
Public procedure PushProperties;
Public procedure PopProperties;
Public function EffectiveSize: Single; virtual;
Public function RealSize: Single; deprecated 'use EffectiveSize';
Public procedure AddFontSizeChangeNotification(const Notify: TNotifyEvent);
Public procedure RemoveFontSizeChangeNotification(const Notify: TNotifyEvent);
Public constructor Create(AOwner: TComponent); overload; override;
Public destructor Destroy; override;
Public function PropertySections(const PropertyName: String): TPropertySections; override;
Public function FontLoaded: Boolean; overload; override;
Public constructor Create(const Url: String; const ASize: Cardinal; const AnAntiAliased: Boolean; const ACharacters: TUnicodeCharSet = nil); reintroduce; overload; deprecated 'use Create(Owner: TComponent), then assign properties to load font: OptimalSize, LoadCharacters, AntiAliased, Url';
Public constructor Create(const Url: String; const ASize: Cardinal; const AnAntiAliased: Boolean; const ACharacters: TSetOfChars); reintroduce; overload; deprecated 'use Create(Owner: TComponent), then assign properties to load font: OptimalSize, LoadCharacters, AntiAliased, Url';
Public procedure Load(const Url: String; const ASize: Cardinal; const AnAntiAliased: Boolean; const ACharacters: TUnicodeCharSet = nil; const AdjustProperties: Boolean = true); overload; deprecated 'assign properties to load font: OptimalSize, LoadCharacters, AntiAliased, Url';
Public procedure Load(const Data: TTextureFontData; const OwnsData: Boolean = false; const AdjustProperties: Boolean = true); overload;
Public procedure PrepareResources; override;
Public procedure Print(const X, Y: Single; const Color: TCastleColor; const S: String); override;
Public function TextWidth(const S: String): Single; override;
Public function TextHeight(const S: String): Single; override;
Public function TextHeightBase(const S: String): Single; override;
Public function TextMove(const S: String): TVector2; override;

Properties

Public property NonVisualComponents [const Index: Integer]: TComponent read GetNonVisualComponents;
Public property IsLoading: Boolean read FIsLoading;
Public property Size: Single read FSize write SetSize;
Public property Outline: Cardinal read FOutline write SetOutline default 0;
Public property OutlineHighQuality: boolean read FOutlineHighQuality write FOutlineHighQuality default false;
Public property OutlineColor: TCastleColor read FOutlineColor write FOutlineColor;
Public property TargetImage: TCastleImage read FTargetImage write FTargetImage;
Published property MeasureHeight: String read FMeasureHeight write SetMeasureHeight stored StoreMeasureHeight;
Published property MeasureCapHeight: String read FMeasureCapHeight write SetMeasureCapHeight stored StoreMeasureCapHeight;
Published property MeasureDescenderHeight: String read FMeasureDescenderHeight write SetMeasureDescenderHeight stored StoreMeasureDescenderHeight;
Public property FontData: TTextureFontData read FFont; deprecated 'you should not need to use this directly';
Public property Scale: Single read GetScale write SetScale;
Published property Url: String read FUrl write SetUrl;
Published property DistanceField: Boolean read FDistanceField write SetDistanceField default false;
Published property OptimalSize: Cardinal read FOptimalSize write SetOptimalSize default DefaultOptimalSize;
Published property AntiAliased: Boolean read FAntiAliased write SetAntiAliased default true;
Published property LoadBasicCharacters: Boolean read FLoadBasicCharacters write SetLoadBasicCharacters default true;
Published property LoadCharacters: String read FLoadCharacters write SetLoadCharacters;

Description

Constants

Public DefaultMeasureHeight = 'AOHIypq';

This item is declared in ancestor TCastleAbstractFont.

This item has no description.

Source: fonts/castlefonts_abstractfont.inc (line 64).

Public DefaultMeasureCapHeight = 'HI';

This item is declared in ancestor TCastleAbstractFont.

This item has no description.

Source: fonts/castlefonts_abstractfont.inc (line 65).

Public DefaultMeasureDescenderHeight = 'ya';

This item is declared in ancestor TCastleAbstractFont.

This item has no description.

Source: fonts/castlefonts_abstractfont.inc (line 66).

Public DefaultOptimalSize = 20;

This item has no description.

Source: fonts/castlefonts_font.inc (line 59).

Methods

Protected function GetInternalText: String; virtual;

This item is declared in ancestor TCastleComponent.

This item has no description.

Source: base/castleclassutils.pas (line 575).

Protected procedure SetInternalText(const Value: String); virtual;

This item is declared in ancestor TCastleComponent.

This item has no description.

Source: base/castleclassutils.pas (line 576).

Protected procedure SetName(const Value: TComponentName); override;

This item is declared in ancestor TCastleComponent.

This item has no description.

Source: base/castleclassutils.pas (line 577).

Protected procedure TranslateProperties(const TranslatePropertyEvent: TTranslatePropertyEvent); virtual;

This item is declared in ancestor TCastleComponent.

Enumerate all properties that are possible to translate in this component. E.g. in TCastleLabel it will return TCastleLabel.Caption, in TCastleEdit it will return TCastleEdit.Text and TCastleEdit.Placeholder.

Returns only non-empty properties, thus assuming that if current (by convention, English) text is empty, then there is no point in translating it. Moreover descendants may define boolean properties to exclude particular text from translating, e.g. TCastleLabel.CaptionTranslate, TCastleEdit.TextTranslate, TCastleEdit.PlaceholderTranslate.

It is not recursive (it doesn't enumerate children properties). Use global TranslateProperties procedure to call this on a hierarchy of TComponent.

You usually don't want to call this method (it is called by other engine routines). But you may find it useful to override this, if you define new component.

Source: base/castleclassutils.pas (line 598).

Public procedure CustomSerialization(const SerializationProcess: TSerializationProcess); virtual;

This item is declared in ancestor TCastleComponent.

Override this method to call various methods of SerializationProcess, which in turn allows to serialize/deserialize things that are not published. This allows to serialize/deserialize with more freedom, e.g. to serialize/deserialize some private field.

Source: base/castleclassutils.pas (line 610).

Public procedure SetTransient;

This item is declared in ancestor TCastleComponent.

Ignore this component when serializing parent's TCastleUserInterface.Controls list or TCastleTransform.List, and do not show this component in CGE editor. This simply sets csTransient flag in ComponentStyle.

This is useful for children that are automatically managed by the parent, and should not be modified by user code. For example, TCastleCheckbox is internally composed from TCastleImageControl and TCastleLabel children, but we don't want to serialize or even show these children to user.

Note that if you want to prevent this component from serializing as part of TCastleUserInterface.Controls list or TCastleTransform.List, but you still want it to be visible in CGE editor, then make it a "subcomponent" instead, by SetSubComponent(true).

Note that both csSubComponent and csTransient only disable the component serialization as part of parent's lists enumerated by CustomSerialization (see internal TCastleUserInterface.SerializeChildrenEnumerate , TCastleTransform.SerializeChildrenEnumerate, TCastleTransform.SerializeBehaviorsEnumerate).

If you will make the component published in its own property (which is normal for "subcomponents") then it will be serialized anyway, just as part of it's own property (like TCastleScrollView.ScrollArea). So to really avoid serializing a children component make it csSubComponent and/or csTransient, and do not publish it.

Source: base/castleclassutils.pas (line 663).

Public procedure AddNonVisualComponent(const NonVisualComponent: TComponent);

This item is declared in ancestor TCastleComponent.

Add non-visual component to this component. This is used to organize non-visual components in a tree hierarchy, in CGE designs and editor.

See also
NonVisualComponentsCount
Count of components added by AddNonVisualComponent.
NonVisualComponents
Components added by AddNonVisualComponent.
NonVisualComponentsEnumerate
You can enumerate current non-visual components using loop like for C in MyComponent.NonVisualComponentsEnumerate do ....

Source: base/castleclassutils.pas (line 672).

Public procedure InsertNonVisualComponent(const Index: Integer; const NonVisualComponent: TComponent);

This item is declared in ancestor TCastleComponent.

Insert non-visual component to this component. This is used to organize non-visual components in a tree hierarchy, in CGE designs and editor.

See also
NonVisualComponentsCount
Count of components added by AddNonVisualComponent.
NonVisualComponents
Components added by AddNonVisualComponent.
NonVisualComponentsEnumerate
You can enumerate current non-visual components using loop like for C in MyComponent.NonVisualComponentsEnumerate do ....

Source: base/castleclassutils.pas (line 681).

Public procedure RemoveNonVisualComponent(const NonVisualComponent: TComponent);

This item is declared in ancestor TCastleComponent.

Removes the component previously added by AddNonVisualComponent.

Source: base/castleclassutils.pas (line 684).

Public function NonVisualComponentsIndexOf(const NonVisualComponent: TComponent): Integer;

This item is declared in ancestor TCastleComponent.

Index of the previously added non-visual component. Returns -1 if the component was not found.

Source: base/castleclassutils.pas (line 688).

Public function NonVisualComponentsCount: Integer;

This item is declared in ancestor TCastleComponent.

Count of components added by AddNonVisualComponent.

See also
AddNonVisualComponent
Add non-visual component to this component.
NonVisualComponents
Components added by AddNonVisualComponent.
NonVisualComponentsEnumerate
You can enumerate current non-visual components using loop like for C in MyComponent.NonVisualComponentsEnumerate do ....

Source: base/castleclassutils.pas (line 695).

Public function NonVisualComponentsEnumerate: TNonVisualComponentsEnumerator;

This item is declared in ancestor TCastleComponent.

You can enumerate current non-visual components using loop like for C in MyComponent.NonVisualComponentsEnumerate do .... Do not call this method in other contexts, it is only useful for "for..in" construction.

See also
AddNonVisualComponent
Add non-visual component to this component.

Source: base/castleclassutils.pas (line 705).

Public function ValueIsStreamed: Boolean; virtual;

This item is declared in ancestor TCastleComponent.

Whether the current value of this object should be written to the stream. This should be True if anything inside this object should be serialized (which means it has non-default value or "stored" specifier indicates that it should be serialized).

This is used by CastleComponentSerialize, which is used in Castle Game Engine for all serialization.

In simple cases, this just says whether the current value of this object equals to some default value.

The default implementation of this class returns True (so always write).

Descendants that override this to sometimes return False (so no need to write) must be very careful: any addition of a new field requires extending this method, otherwise new field may not be saved sometimes (when all other fields are default). Descentants of such classes must also be aware of it. This check must include everything that is inside this object in JSON, including subcomponents and children objects (as done e.g. by TSerializationProcess.ReadWriteList). In practice, overriding this method is only reasonable for simple classes that will not change much in the future, like TCastleVector3Persistent.

The name of this method is consistent with TPropertyEditor.ValueIsStreamed in LCL.

Source: base/castleclassutils.pas (line 739).

Public procedure DesignerInfo(const SList: TStrings); virtual;

This item is declared in ancestor TCastleComponent.

Override to add information that should be visible at design-time. Call SList.Add for each new line of information.

Source: base/castleclassutils.pas (line 743).

Public procedure DesignerWarnings(const SList: TStrings); virtual;

This item is declared in ancestor TCastleComponent.

Override to add warnings that should be visible at design-time. Call SList.Add for each new warning.

Source: base/castleclassutils.pas (line 747).

Public procedure PrintAndMove(const s: string); deprecated 'use Print(X, Y, ...), and move the (X, Y) yourself based on TextMove, instead of this';

This item is declared in ancestor TCastleAbstractFont.

Warning: this symbol is deprecated: use Print(X, Y, ...), and move the (X, Y) yourself based on TextMove, instead of this

Draw text at the current WindowPos, and move the WindowPos at the end. This way you can immediately call another PrintAndMove again, to add something at the end.

It is not adviced to use it, as using the global WindowPos leads sooner or later to messy in code, that has to deal with global state. If you need to know how to move after printing text, use TextMove.

Source: fonts/castlefonts_abstractfont.inc (line 93).

Public procedure Print(const X, Y: Single; const Color: TCastleColor; const S: string); overload; virtual; abstract;

This item is declared in ancestor TCastleAbstractFont.

Draw text at the given position with given color. If the last Color component is not 1, the text is rendered with blending.

Overloaded version without X, Y uses WindowPos (but doesn't modify it, in contrast to PrintAndMove). Overloaded version without Color uses CurrentColor, last color set by glColorv. It is not adviced to use overloaded versions without X, Y or Color — using global state leads to messy code. You should upgrade your code to use the version that gets X,Y,Color explicitly.

Source: fonts/castlefonts_abstractfont.inc (line 107).

Public procedure Print(const Pos: TVector2Integer; const Color: TCastleColor; const S: string); overload;

This item is declared in ancestor TCastleAbstractFont.

This item has no description.

Source: fonts/castlefonts_abstractfont.inc (line 109).

Public procedure Print(const Pos: TVector2; const Color: TCastleColor; const S: string); overload;

This item is declared in ancestor TCastleAbstractFont.

This item has no description.

Source: fonts/castlefonts_abstractfont.inc (line 111).

Public procedure Print(const X, Y: Single; const S: string); overload; deprecated 'instead of this, use Print overload that takes explicit X,Y,Color parameters';

This item is declared in ancestor TCastleAbstractFont.

Warning: this symbol is deprecated: instead of this, use Print overload that takes explicit X,Y,Color parameters

This item has no description.

Source: fonts/castlefonts_abstractfont.inc (line 114).

Public procedure Print(const s: string); overload; deprecated 'instead of this, use Print overload that takes explicit X,Y,Color parameters';

This item is declared in ancestor TCastleAbstractFont.

Warning: this symbol is deprecated: instead of this, use Print overload that takes explicit X,Y,Color parameters

This item has no description.

Source: fonts/castlefonts_abstractfont.inc (line 115).

Public procedure PrintRect(const Rect: TRectangle; const Color: TCastleColor; const S: string; const HorizontalAlignment: THorizontalPosition; const VerticalAlignment: TVerticalPosition); overload;

This item is declared in ancestor TCastleAbstractFont.

Print text, aligning within given rectangle.

Hint: Use TRectangle.Grow(-10) or similar to align within a rectangle with padding.

Source: fonts/castlefonts_abstractfont.inc (line 121).

Public procedure PrintRect(const Rect: TFloatRectangle; const Color: TCastleColor; const S: string; const HorizontalAlignment: THorizontalPosition; const VerticalAlignment: TVerticalPosition); overload;

This item is declared in ancestor TCastleAbstractFont.

This item has no description.

Source: fonts/castlefonts_abstractfont.inc (line 125).

Public procedure PrintRectMultiline(const Rect: TRectangle; const Color: TCastleColor; const S: string; const HorizontalAlignment: THorizontalPosition; const VerticalAlignment: TVerticalPosition; const Html: boolean; const LineSpacing: Integer; const TextHorizontalAlignment: THorizontalPosition = hpLeft); overload;

This item is declared in ancestor TCastleAbstractFont.

Print text, aligning within given rectangle. Newlines within the text will be automatically honored, the text will be rendered as multiple lines. See PrintStrings for description of parameters Html, LineSpacing, TextHorizontalAlignment.

Source: fonts/castlefonts_abstractfont.inc (line 135).

Public procedure PrintRectMultiline(const Rect: TFloatRectangle; const Color: TCastleColor; const S: string; const HorizontalAlignment: THorizontalPosition; const VerticalAlignment: TVerticalPosition; const Html: boolean; const LineSpacing: Integer; const TextHorizontalAlignment: THorizontalPosition = hpLeft); overload;

This item is declared in ancestor TCastleAbstractFont.

This item has no description.

Source: fonts/castlefonts_abstractfont.inc (line 142).

Public function TextWidth(const S: string): Single; virtual; abstract;

This item is declared in ancestor TCastleAbstractFont.

This item has no description.

Source: fonts/castlefonts_abstractfont.inc (line 159).

Public function TextHeight(const S: string): Single; virtual; abstract;

This item is declared in ancestor TCastleAbstractFont.

This item has no description.

Source: fonts/castlefonts_abstractfont.inc (line 160).

Public function TextHeightBase(const S: string): Single; virtual; abstract;

This item is declared in ancestor TCastleAbstractFont.

The height (above the baseline) of the text. This doesn't take into account height of the text below the baseline (for example letter "y" has the tail below the baseline in most fonts).

Source: fonts/castlefonts_abstractfont.inc (line 164).

Public function TextMove(const S: string): TVector2; virtual; abstract;

This item is declared in ancestor TCastleAbstractFont.

This item has no description.

Source: fonts/castlefonts_abstractfont.inc (line 165).

Public function TextSize(const S: string): TVector2;

This item is declared in ancestor TCastleAbstractFont.

This item has no description.

Source: fonts/castlefonts_abstractfont.inc (line 166).

Public function RowHeight: Single; deprecated 'use Height';

This item is declared in ancestor TCastleAbstractFont.

Warning: this symbol is deprecated: use Height

This item has no description.

Source: fonts/castlefonts_abstractfont.inc (line 168).

Public function RowHeightBase: Single; deprecated 'use CapHeight';

This item is declared in ancestor TCastleAbstractFont.

Warning: this symbol is deprecated: use CapHeight

This item has no description.

Source: fonts/castlefonts_abstractfont.inc (line 169).

Public function Descend: Single; deprecated 'use DescenderHeight';

This item is declared in ancestor TCastleAbstractFont.

Warning: this symbol is deprecated: use DescenderHeight

This item has no description.

Source: fonts/castlefonts_abstractfont.inc (line 170).

Public function Height: Single;

This item is declared in ancestor TCastleAbstractFont.

Maximum height of font characters, taking into account whole descent and ascent.

By default calculated as height of "AOHIypq", see the MeasureHeight.

See about standard font measurements: https://en.wikipedia.org/wiki/Typeface#Font_metrics , https://en.wikipedia.org/wiki/Metric_typographic_units .

Source: fonts/castlefonts_abstractfont.inc (line 179).

Public function CapHeight: Single;

This item is declared in ancestor TCastleAbstractFont.

Height above the baseline of font characters.

Compared to Height, this does not take into account the characters size below the baseline, and it doesn't take into account some possible "overflow" on the top of some characters.

By default calculated as height of "HI", see the MeasureCapHeight.

The intention is that, while this doesn't represent the whole possible font height, but it often represents the perceived by user height of the block of text, as fonts are designed to make descents / overflows not stand out.

See about standard font measurements: https://en.wikipedia.org/wiki/Typeface#Font_metrics , https://en.wikipedia.org/wiki/Metric_typographic_units . About "cap height" in particular: https://en.wikipedia.org/wiki/Cap_height https://fonts.google.com/knowledge/glossary/cap_height

Source: fonts/castlefonts_abstractfont.inc (line 199).

Public function DescenderHeight: Single;

This item is declared in ancestor TCastleAbstractFont.

How low the font characters may go below the baseline. By default calculated as a difference between "y" and "a" characters height, see the MeasureDescenderHeight.

See about standard font measurements: https://en.wikipedia.org/wiki/Typeface#Font_metrics , https://en.wikipedia.org/wiki/Metric_typographic_units .

Source: fonts/castlefonts_abstractfont.inc (line 208).

Public procedure BreakLines(const unbroken: string; broken: TStrings; MaxLineWidth: Single); overload;

This item is declared in ancestor TCastleAbstractFont.

Break lines (possibly break one long string into more strings) to fit the text with given MaxLineWidth.

This takes into account current font information (works also for non-monospace fonts, of course), and converts your Unbroken text into Broken text, such that TextWidth of the longest Broken line fits within MaxLineWidth.

Tries to break on white characters. If not possible (there's a long stream of non-white characters that really has to be broken), it will break in the middle of normal (non-white) characters. The only situation when we have to fail, and the resulting Broken text is wider than required MaxLineWidth, is when a single character in your font is wider than MaxLineWidth. In such case, there's really no solution, and we'll just let such character stay.

If you use the overloaded version where Unbroken is just a string, then note that already existing newlines (NL) inside Unbroken will be correctly preserved.

If you use the overloaded version with separate Unbroken and Broken parameters, then the previous Broken contents are not modified. We only append to Broken new strings, coming from Unbroken text. The overloaded version that takes only Broken parameter (no Unbroken parameter) simply modifies it's Broken parameter (from the line FirstToBreak).

Source: fonts/castlefonts_abstractfont.inc (line 239).

Public procedure BreakLines(unbroken, broken: TStrings; MaxLineWidth: Single); overload;

This item is declared in ancestor TCastleAbstractFont.

This item has no description.

Source: fonts/castlefonts_abstractfont.inc (line 240).

Public procedure BreakLines(broken: TStrings; MaxLineWidth: Single; FirstToBreak: integer); overload;

This item is declared in ancestor TCastleAbstractFont.

This item has no description.

Source: fonts/castlefonts_abstractfont.inc (line 241).

Public function MaxTextWidth(SList: TStrings; const Html: boolean = false): Single;

This item is declared in ancestor TCastleAbstractFont.

Largest width of the line of text in given list.

Parameters
Html
Indicates that strings inside SList use a subset of HTML, the same ones as interpreted by PrintStrings. If your SList uses these elements (for example, you plan to call later PrintStrings with the same SList and Html = True) then make sure you pass Html = True to this method. Otherwise, MaxTextWidth will treat HTML markup (like <font ...>) like a normal text, usually making the width incorrectly large.

Source: fonts/castlefonts_abstractfont.inc (line 254).

Public procedure PrintStrings(const X0, Y0: Single; const Color: TCastleColor; const Strs: TStrings; const Html: boolean; const LineSpacing: Single; const TextHorizontalAlignment: THorizontalPosition = hpLeft); overload;

This item is declared in ancestor TCastleAbstractFont.

Print all strings from the list.

Parameters
X0
The X position of the whole text block. It's exact interpretation depends on TextHorizontalAlignment value.
Y0
The bottom position of the whole text block. That is, this is the bottom position of the last string.
Color
The color of the text. Alpha value of the color is honored, value < 1 renders partially-transparent text.

Overloaded and deprecated versions without explicit Color parameter use CurrentColor.

Strs
The text to display. Can be given as either TStringList, or a simple array of strings.
Html
Enable a subset of HTML to mark font changes inside the text. See the example examples/fonts/html_text_demo.html for a demo, supported HTML constructs now are:

  • <b> (bold)

  • <i> (italic)

  • <font color="#rrggbb">, <font color="#rrggbbaa"> (change color, with or without alpha)

  • <font size="xxx">, <small> (change size)

  • <br> <br/> <br /> <p> (newlines; paragraph makes 2 newlines)

  • &amp; &lt; &gt; &apos; &quot; (entities)

  • <!– xxx –> (comments)

LineSpacing
Extra space between lines. Distance between each line is determined by Height + LineSpacing pixels.

Note that LineSpacing can be < 0 (as well as > 0), this may be sometimes useful if you really want to squeeze more text into the available space. Still, make sure that (Height + LineSpacing) is > 0.

Source: fonts/castlefonts_abstractfont.inc (line 297).

Public procedure PrintStrings(const X0, Y0: Single; const Color: TCastleColor; const Strs: array of string; const Html: boolean; const LineSpacing: Single; const TextHorizontalAlignment: THorizontalPosition = hpLeft); overload;

This item is declared in ancestor TCastleAbstractFont.

This item has no description.

Source: fonts/castlefonts_abstractfont.inc (line 301).

Public procedure PrintStrings(const Strs: TStrings; const Html: boolean; const LineSpacing: Single; const X0: Single = 0; const Y0: Single = 0); overload; deprecated 'instead of this, use PrintStrings version that takes explicit Color parameter';

This item is declared in ancestor TCastleAbstractFont.

Warning: this symbol is deprecated: instead of this, use PrintStrings version that takes explicit Color parameter

This item has no description.

Source: fonts/castlefonts_abstractfont.inc (line 305).

Public procedure PrintStrings(const Strs: array of string; const Html: boolean; const LineSpacing: Single; const X0: Single = 0; const Y0: Single = 0); overload; deprecated 'instead of this, use PrintStrings version that takes explicit Color parameter';

This item is declared in ancestor TCastleAbstractFont.

Warning: this symbol is deprecated: instead of this, use PrintStrings version that takes explicit Color parameter

This item has no description.

Source: fonts/castlefonts_abstractfont.inc (line 308).

Public function PrintBrokenString(const Rect: TRectangle; const Color: TCastleColor; const S: string; const LineSpacing: Single; const AlignHorizontal: THorizontalPosition; const AlignVertical: TVerticalPosition; const Html: boolean = false): Integer; overload;

This item is declared in ancestor TCastleAbstractFont.

Print the string, broken such that it fits within MaxLineWidth. The string is broken into many lines using BreakLines, so the original newlines insides are correctly used, and the length of lines fits inside MaxLineWidth.

The strings are printed on the screen, just like by PrintStrings. If PositionsFirst then the X0, Y0 determine the position of the first (top) line, otherwise they determine the position of the last (bottom) line.

LineSpacing has the same meaning as for PrintStrings: it adds an additional space between lines (if positive) or forces the lines to be more tightly squeezed (if negative). Always make sure that (Height + LineSpacing) > 0.

Returns the number of lines printed, that is the number of lines after breaking the text into lines. This may be useful e.g. to calculate the height of the printed text.

Overloaded and deprecated version without explicit Color parameter uses CurrentColor.

Overloaded version that takes rectangle as a parameter can align the resulting string box within the rectangle.

Source: fonts/castlefonts_abstractfont.inc (line 339).

Public function PrintBrokenString(const Rect: TFloatRectangle; const Color: TCastleColor; const S: string; const LineSpacing: Single; const AlignHorizontal: THorizontalPosition; const AlignVertical: TVerticalPosition; const Html: boolean = false): Integer; overload;

This item is declared in ancestor TCastleAbstractFont.

This item has no description.

Source: fonts/castlefonts_abstractfont.inc (line 345).

Public function PrintBrokenString(X0, Y0: Single; const Color: TCastleColor; const S: string; const MaxLineWidth: Single; const PositionsFirst: boolean; const LineSpacing: Single; const Html: boolean = false): Integer; overload;

This item is declared in ancestor TCastleAbstractFont.

This item has no description.

Source: fonts/castlefonts_abstractfont.inc (line 351).

Public function PrintBrokenString(const S: string; const MaxLineWidth, X0, Y0: Single; const PositionsFirst: boolean; const LineSpacing: Single): Integer; overload; deprecated 'instead of this, use PrintBrokenString that takes explicit Color parameter';

This item is declared in ancestor TCastleAbstractFont.

Warning: this symbol is deprecated: instead of this, use PrintBrokenString that takes explicit Color parameter

This item has no description.

Source: fonts/castlefonts_abstractfont.inc (line 356).

Public procedure PushProperties;

This item is declared in ancestor TCastleAbstractFont.

Save draw properties to a stack. Saves: Size, Outline, OutlineColor, OutlineHighQuality, TargetImage.

Source: fonts/castlefonts_abstractfont.inc (line 388).

Public procedure PopProperties;

This item is declared in ancestor TCastleAbstractFont.

This item has no description.

Source: fonts/castlefonts_abstractfont.inc (line 389).

Public function EffectiveSize: Single; virtual;

This item is declared in ancestor TCastleAbstractFont.

Non-zero font size. Usually same thing as Size, but in case of proxy font classes (like TCustomizedFont and TCastleFontFamily) it makes sure to never return zero (which, in case of font proxies, is allowed value for Size and means "use underlying font size").

Source: fonts/castlefonts_abstractfont.inc (line 395).

Public function RealSize: Single; deprecated 'use EffectiveSize';

This item is declared in ancestor TCastleAbstractFont.

Warning: this symbol is deprecated: use EffectiveSize

This item has no description.

Source: fonts/castlefonts_abstractfont.inc (line 397).

Public procedure AddFontSizeChangeNotification(const Notify: TNotifyEvent);

This item is declared in ancestor TCastleAbstractFont.

Add notification when FontSizesChanged occurs.

Source: fonts/castlefonts_abstractfont.inc (line 421).

Public procedure RemoveFontSizeChangeNotification(const Notify: TNotifyEvent);

This item is declared in ancestor TCastleAbstractFont.

Remove notification when FontSizesChanged occurs.

Source: fonts/castlefonts_abstractfont.inc (line 423).

Public constructor Create(AOwner: TComponent); overload; override;

This item has no description.

Source: fonts/castlefonts_font.inc (line 61).

Public destructor Destroy; override;

This item has no description.

Source: fonts/castlefonts_font.inc (line 62).

Public function PropertySections(const PropertyName: String): TPropertySections; override;

This item has no description. Showing description inherited from TCastleComponent.PropertySections.

Section where to show property in the editor.

Source: fonts/castlefonts_font.inc (line 63).

Public function FontLoaded: Boolean; overload; override;

This item has no description. Showing description inherited from TCastleAbstractFont.FontLoaded.

If the font is loaded, it can actually display and measure some characters.

Source: fonts/castlefonts_font.inc (line 64).

Public constructor Create(const Url: String; const ASize: Cardinal; const AnAntiAliased: Boolean; const ACharacters: TUnicodeCharSet = nil); reintroduce; overload; deprecated 'use Create(Owner: TComponent), then assign properties to load font: OptimalSize, LoadCharacters, AntiAliased, Url';

Warning: this symbol is deprecated: use Create(Owner: TComponent), then assign properties to load font: OptimalSize, LoadCharacters, AntiAliased, Url

This item has no description.

Source: fonts/castlefonts_font.inc (line 66).

Public constructor Create(const Url: String; const ASize: Cardinal; const AnAntiAliased: Boolean; const ACharacters: TSetOfChars); reintroduce; overload; deprecated 'use Create(Owner: TComponent), then assign properties to load font: OptimalSize, LoadCharacters, AntiAliased, Url';

Warning: this symbol is deprecated: use Create(Owner: TComponent), then assign properties to load font: OptimalSize, LoadCharacters, AntiAliased, Url

This item has no description.

Source: fonts/castlefonts_font.inc (line 69).

Public procedure Load(const Url: String; const ASize: Cardinal; const AnAntiAliased: Boolean; const ACharacters: TUnicodeCharSet = nil; const AdjustProperties: Boolean = true); overload; deprecated 'assign properties to load font: OptimalSize, LoadCharacters, AntiAliased, Url';

Warning: this symbol is deprecated: assign properties to load font: OptimalSize, LoadCharacters, AntiAliased, Url

Load by reading a FreeType font file, like ttf.

Providing charaters list as Nil means that we only create glyphs for SimpleAsciiCharacters, which includes only the basic ASCII characters. The ACharacters instance does not become owned by this object, so remember to free it after calling this constructor.

Loading a font data also changes Size to the underlying (optimal to render) font data size.

Source: fonts/castlefonts_font.inc (line 82).

Public procedure Load(const Data: TTextureFontData; const OwnsData: Boolean = false; const AdjustProperties: Boolean = true); overload;

Load from a ready TTextureFontData instance.

Parameters
Data
TTextureFontData instance containing loaded image and glyphs parameters.
OwnsData
If True, the Data instance becomes owned by this class (will be freed in our constructor). Usually you do not want this, since usually you pass Data from a unit generated by texture-font-to-pascal. In this case, the finalization of CastleTextureFont_Xxx unit will already free the TTextureFontData instance.
AdjustProperties
Adjust Url, OptimalSize, Size, AntiAliased to reflect loaded Data. Or reset them to reflect empty Url (and the rest at defaults) when Data = nil.

Source: fonts/castlefonts_font.inc (line 99).

Public procedure PrepareResources; override;

This item has no description. Showing description inherited from TCastleAbstractFont.PrepareResources.

The font may require some OpenGL resources for drawing. You can explicitly create them using PrepareResources (although it is never needed, resources will be automatically created if needed). There's no public method to explicitly destroy them, they are always destroyed automatically.

Source: fonts/castlefonts_font.inc (line 103).

Public procedure Print(const X, Y: Single; const Color: TCastleColor; const S: String); override;

This item has no description. Showing description inherited from TCastleAbstractFont.Print.

Draw text at the given position with given color. If the last Color component is not 1, the text is rendered with blending.

Overloaded version without X, Y uses WindowPos (but doesn't modify it, in contrast to PrintAndMove). Overloaded version without Color uses CurrentColor, last color set by glColorv. It is not adviced to use overloaded versions without X, Y or Color — using global state leads to messy code. You should upgrade your code to use the version that gets X,Y,Color explicitly.

Source: fonts/castlefonts_font.inc (line 104).

Public function TextWidth(const S: String): Single; override;

This item has no description.

Source: fonts/castlefonts_font.inc (line 106).

Public function TextHeight(const S: String): Single; override;

This item has no description.

Source: fonts/castlefonts_font.inc (line 107).

Public function TextHeightBase(const S: String): Single; override;

This item has no description. Showing description inherited from TCastleAbstractFont.TextHeightBase.

The height (above the baseline) of the text. This doesn't take into account height of the text below the baseline (for example letter "y" has the tail below the baseline in most fonts).

Source: fonts/castlefonts_font.inc (line 108).

Public function TextMove(const S: String): TVector2; override;

This item has no description.

Source: fonts/castlefonts_font.inc (line 109).

Properties

Public property NonVisualComponents [const Index: Integer]: TComponent read GetNonVisualComponents;

This item is declared in ancestor TCastleComponent.

Components added by AddNonVisualComponent.

Source: base/castleclassutils.pas (line 698).

Public property IsLoading: Boolean read FIsLoading;

This item is declared in ancestor TCastleComponent.

Is the component during deserialization now.

Note: We can't use csLoading in ComponentState because in Delphi it is not possible to control it from CastleComponentSerialize.

Source: base/castleclassutils.pas (line 711).

Public property Size: Single read FSize write SetSize;

This item is declared in ancestor TCastleAbstractFont.

Desired font size to use when rendering (Print) and measuring (TextWidth, TextHeight and related). Should be always > 0.

The font size should correspond to the font height, which you can query using Height. So in general Size and Height should be equal. That said, it is up to each specific font file to have correct size that satisfies above. This property, Size, gets and sets the size, as understood by FreeType font size. On the other hand, the CapHeight and Height properties actually query the letters height.

Source: fonts/castlefonts_abstractfont.inc (line 84).

Public property Outline: Cardinal read FOutline write SetOutline default 0;

This item is declared in ancestor TCastleAbstractFont.

Outline size around the normal text. Note that the current implementation is very simple, it will only look sensible for small outline values (like 1 or 2).

Note that outline size, in pixels, is not scaled along with font size. Which makes sense: whether you load TTF with size 10 and then set size 20, or you load TTF with size 40 and then set size 20 — the font is internally scaled differently, but the resulting sizes and outline sizes remain the same.

See also
OutlineHighQuality
Optionally force better outline quality.

Source: fonts/castlefonts_abstractfont.inc (line 373).

Public property OutlineHighQuality: boolean read FOutlineHighQuality write FOutlineHighQuality default false;

This item is declared in ancestor TCastleAbstractFont.

Optionally force better outline quality. Used only if Outline <> 0. High quality outline looks better, but is about 2x more expensive to draw.

See also
Outline
Outline size around the normal text.

Source: fonts/castlefonts_abstractfont.inc (line 378).

Public property OutlineColor: TCastleColor read FOutlineColor write FOutlineColor;

This item is declared in ancestor TCastleAbstractFont.

Outline color, used only if Outline <> 0. Default is black.

See also
Outline
Outline size around the normal text.

Source: fonts/castlefonts_abstractfont.inc (line 383).

Public property TargetImage: TCastleImage read FTargetImage write FTargetImage;

This item is declared in ancestor TCastleAbstractFont.

The image where we render the font. Usually (when this is Nil) our rendering routines render to the screen (or the current FBO, if you use TGLRenderToTexture). By setting this to non-nil, you make the rendering by done on CPU (without libraries like OpenGL/OpenGLES), and the text is drawn on the given image.

The PushProperties and PopProperties methods save/restore this.

TODO: Font scaling (normally done by TCastleFont and TCastleBitmapFont if you change Size from default) is not done when drawing font to an image. So don't touch the Size if you plan on rendering to image. Also, when using HTML tags, do not change the font size by them. Otherwise TextWidth / TextHeight will be unsynchronized with what Print actually does — so not only your font will remain constant size, also it will overlap with itself. This will get fixed one day — TCastleImage.Draw just needs to support scaling.

Source: fonts/castlefonts_abstractfont.inc (line 418).

Published property MeasureHeight: String read FMeasureHeight write SetMeasureHeight stored StoreMeasureHeight;

This item is declared in ancestor TCastleAbstractFont.

Use these characters to measure font Height.

Source: fonts/castlefonts_abstractfont.inc (line 426).

Published property MeasureCapHeight: String read FMeasureCapHeight write SetMeasureCapHeight stored StoreMeasureCapHeight;

This item is declared in ancestor TCastleAbstractFont.

Use these characters to measure font CapHeight. Note that we only measure the height above baseline (Y = 0), so even when MeasureHeight and MeasureCapHeight are equal, the resulting Height and CapHeight may differ.

Source: fonts/castlefonts_abstractfont.inc (line 433).

Published property MeasureDescenderHeight: String read FMeasureDescenderHeight write SetMeasureDescenderHeight stored StoreMeasureDescenderHeight;

This item is declared in ancestor TCastleAbstractFont.

Use these characters to measure font DescenderHeight.

This string must be empty (meaning that descend is zero) or has exactly 2 characters. The descender height is measured as height of 1st char - height of 2nd char.

See DefaultMeasureDescenderHeight .

Source: fonts/castlefonts_abstractfont.inc (line 443).

Public property FontData: TTextureFontData read FFont; deprecated 'you should not need to use this directly';

Warning: this symbol is deprecated: you should not need to use this directly

Underlying font data.

Source: fonts/castlefonts_font.inc (line 112).

Public property Scale: Single read GetScale write SetScale;

Scale applied to the rendered font, compared to FontData.Size. Changing this is equivalent to changing the Size property.

Source: fonts/castlefonts_font.inc (line 116).

Published property Url: String read FUrl write SetUrl;

Loaded font file. Typically this is used for outline (scalable, vector) fonts in ttf or otf formats. But it can really deal with any font format supported by the FreeType library, even bitmap fonts, see the summary of font formats supported by FreeType.

Source: fonts/castlefonts_font.inc (line 123).

Published property DistanceField: Boolean read FDistanceField write SetDistanceField default false;

Use "distance field" font rendering. This is a font rendering technique that may result in a better quality when the text is large.

Underneath, the font is processed to a different texture than usual (that expresses distances to glyphs) and rendered usign a special shader.

The positive outcome is that the font looks better (not blurred) even when scaled up. "Scaling up" occurs when the actual font size (derived from TCastleUserInterfaceFont.FontSize and UI scaling) is significantly larger than the optimal size for which the font image was prepared (OptimalSize). In this case, rendering without distance field (when this is False, by default) results in blurred font look. When this is True, the look remains "crisp".

Disadvantages:

One, preparing a distance field font texture is more time-consuming. So loading time may be slightly larger. This increased loading time is generally negligible if you just have a few fonts. But be sure to profile your loading time (see https://castle-engine.io/manual_optimization.php ) if you use a lot of fonts with DistanceField = True.

A more serious disadvantage is that the result is not always a better quality: At really large sizes, the artifacts of distance field rendering may be visible – the letters are "crisp" but their shape may be slightly distorted. If you don't mind extra memory usage, you can likely get better quality by just loading a larger font texture (with larger OptimalSize) and leaving this property at False.

Morover, when the final font size is *smaller* than the size for which the font was prepared, it will definitely look worse.

TODO: We could defeat some of the issues mentioned above. You're welcome to ping us ( https://castle-engine.io/talk.php ) and support ( https://www.patreon.com/castleengine ) to make it happen.

  • The loading time of fonts (with and without distance fields) could be improved by generating the necessary texture at preprocessing, introducing "castle-engine auto-generate" command that would generalize current "castle-engine auto-generate-textures".

  • TCastleText (text in a viewport) cannot handle fonts with DistanceField yet. Result would not be sensible. For now, TCastleText.FontStyleFontChanged warns about it and forces DistanceField to False.

  • It is possible that the quality could be improved:

    Implement normalization. Can this make downscaling better? Does this make upscaling better? See https://libgdx.com/wiki/graphics/2d/fonts/distance-field-fonts what it means.

  • Introduce a fallback on non-distance-field texture, used when downscaling happens?

    This means larger memory usage, and potential jump in look if someone animates FontSize.

Source: fonts/castlefonts_font.inc (line 192).

Published property OptimalSize: Cardinal read FOptimalSize write SetOptimalSize default DefaultOptimalSize;

Optimal font size (in real device pixels), the font will be scaled when other size is actually needed. This also sets default Size used for rendering this font.

Source: fonts/castlefonts_font.inc (line 198).

Published property AntiAliased: Boolean read FAntiAliased write SetAntiAliased default true;

Anti-aliased font has smooth edges and is rendered using blending. Usually this is much better for quality. Non-anti-aliased means that font uses simple yes/no transparency and is rendered using alpha testing.

Source: fonts/castlefonts_font.inc (line 204).

Published property LoadBasicCharacters: Boolean read FLoadBasicCharacters write SetLoadBasicCharacters default true;

Load from font all "basic" characters, which include digits, English letters and standard ASCII symbols. See SimpleAsciiCharacters for exact definition. These are loaded in addition to characters listed on LoadCharacters.

Source: fonts/castlefonts_font.inc (line 210).

Published property LoadCharacters: String read FLoadCharacters write SetLoadCharacters;

Load from font all characters listed here. As everywhere in CGE (same as in Lazarus LCL), this is an String composed from UTF-8 characters.

Source: fonts/castlefonts_font.inc (line 214).

Generated by PasDoc 0.17.0.snapshot.

Copyright Michalis Kamburelis and Castle Game Engine Contributors.

This webpage is also open-source and we welcome pull requests to improve it.

We use cookies for analytics. See our privacy policy.