Class TCastleAbstractFont

Unit

Declaration

type TCastleAbstractFont = class abstract(TCastleComponent)

Description

Abstract class for a font that can be used to render text.

Hierarchy

Overview

Fields

Public nested const DefaultMeasureHeight = 'AOHIypq';
Public nested const DefaultMeasureCapHeight = 'HI';
Public nested const DefaultMeasureDescenderHeight = 'ya';

Methods

Public constructor Create(AOwner: TComponent); override;
Public destructor Destroy; override;
Public function FontLoaded: Boolean; virtual; abstract;
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 procedure PrepareResources; virtual;
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);

Properties

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;

Description

Fields

Public nested const DefaultMeasureHeight = 'AOHIypq';

This item has no description.

Public nested const DefaultMeasureCapHeight = 'HI';

This item has no description.

Public nested const DefaultMeasureDescenderHeight = 'ya';

This item has no description.

Methods

Public constructor Create(AOwner: TComponent); override;

This item has no description.

Public destructor Destroy; override;

This item has no description.

Public function FontLoaded: Boolean; virtual; abstract;

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

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

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.

May require 1 free slot on the attributes stack. May only be called when current matrix is modelview. Doesn't modify any OpenGL state or matrix, except it moves raster position.

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

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.

May require 1 free slot on the attributes stack. May only be called when current matrix is modelview. Doesn't modify any OpenGL state or matrix, except it moves raster position.

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

This item has no description.

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

This item has no description.

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';

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

This item has no description.

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

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

This item has no description.

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

Print text, aligning within given rectangle.

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

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

This item has no description.

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;

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.

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 has no description.

Public procedure PrepareResources; virtual;

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.

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

This item has no description.

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

This item has no description.

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

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).

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

This item has no description.

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

This item has no description.

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

Warning: this symbol is deprecated: use Height

This item has no description.

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

Warning: this symbol is deprecated: use CapHeight

This item has no description.

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

Warning: this symbol is deprecated: use DescenderHeight

This item has no description.

Public function Height: Single;

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 .

Public function CapHeight: Single;

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

Public function DescenderHeight: Single;

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 .

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

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).

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

This item has no description.

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

This item has no description.

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

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.
Public procedure PrintStrings(const X0, Y0: Single; const Color: TCastleColor; const Strs: TStrings; const Html: boolean; const LineSpacing: Single; const TextHorizontalAlignment: THorizontalPosition = hpLeft); overload;

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.

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 has no description.

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';

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

This item has no description.

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';

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

This item has no description.

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;

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.

May require 1 free slot on the attributes stack. May only be called when current matrix is modelview. Doesn't modify any OpenGL state or matrix.

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.

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 has no description.

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 has no description.

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';

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

This item has no description.

Public procedure PushProperties;

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

Public procedure PopProperties;

This item has no description.

Public function EffectiveSize: Single; virtual;

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").

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

Warning: this symbol is deprecated: use EffectiveSize

This item has no description.

Public procedure AddFontSizeChangeNotification(const Notify: TNotifyEvent);

Add notification when FontSizesChanged occurs.

Public procedure RemoveFontSizeChangeNotification(const Notify: TNotifyEvent);

Remove notification when FontSizesChanged occurs.

Properties

Public property Size: Single read FSize write SetSize;

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.

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

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.
Public property OutlineHighQuality: boolean read FOutlineHighQuality write FOutlineHighQuality default false;

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.
Public property OutlineColor: TCastleColor read FOutlineColor write FOutlineColor;

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

See also
Outline
Outline size around the normal text.
Public property TargetImage: TCastleImage read FTargetImage write FTargetImage;

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.

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

Use these characters to measure font Height.

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

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.

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

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 .


Generated by PasDoc 0.16.0-snapshot.