Castle Game Engine: CastleFonts: Class TCastleFont

# Class TCastleFont
Description | Hierarchy | Fields | Methods | Properties
## Unit CastleFonts ## Declaration `type TCastleFont = class abstract(TObject)` ## Description Abstract class for 2D font. ## Hierarchy TObject TCastleFont ## Overview ### Methods
| `constructor Create;`
| `destructor Destroy; override;`
| `procedure PrintAndMove(const s: string); deprecated;`
| `procedure Print(const X, Y: Integer; const Color: TCastleColor; const S: string); overload; virtual; abstract;`
| `procedure Print(const Pos: TVector2Integer; const Color: TCastleColor; const S: string); overload;`
| `procedure Print(const X, Y: Integer; const S: string); overload; deprecated;`
| `procedure Print(const s: string); overload; deprecated;`
| `procedure PrintRect(const Rect: TRectangle; const Color: TCastleColor; const S: string; const HorizontalAlignment: THorizontalPosition; const VerticalAlignment: TVerticalPosition);`
| `procedure PrintRectMultiline(const Rect: TRectangle; const Color: TCastleColor; const S: string; const HorizontalAlignment: THorizontalPosition; const VerticalAlignment: TVerticalPosition; const Tags: boolean; const LineSpacing: Integer; const TextHorizontalAlignment: THorizontalPosition = hpLeft);`
| `procedure GLContextOpen; virtual;`
| `procedure GLContextClose; virtual;`
| `function TextWidth(const S: string): Integer; virtual; abstract;`
| `function TextHeight(const S: string): Integer; virtual; abstract;`
| `function TextHeightBase(const S: string): Integer; virtual; abstract;`
| `function TextMove(const S: string): TVector2Integer; virtual; abstract;`
| `function TextSize(const S: string): TVector2Integer;`
| `function RowHeight: Integer;`
| `function RowHeightBase: Integer;`
| `function Descend: Integer;`
| `procedure BreakLines(const unbroken: string; broken: TStrings; MaxLineWidth: integer); overload;`
| `procedure BreakLines(unbroken, broken: TStrings; MaxLineWidth: integer); overload;`
| `procedure BreakLines(broken: TStrings; MaxLineWidth: Integer; FirstToBreak: integer); overload;`
| `function MaxTextWidth(SList: TStrings; const Tags: boolean = false): Integer;`
| `procedure PrintStrings(const X0, Y0: Integer; const Color: TCastleColor; const Strs: TStrings; const Tags: boolean; const LineSpacing: Integer; const TextHorizontalAlignment: THorizontalPosition = hpLeft); overload;`
| `procedure PrintStrings(const Strs: TStrings; const Tags: boolean; const LineSpacing: Integer; const X0: Integer = 0; const Y0: Integer = 0); overload; deprecated;`
| `procedure PrintStrings(const Strs: array of string; const Tags: boolean; const LineSpacing: Integer; const X0: Integer = 0; const Y0: Integer = 0); overload; deprecated;`
| `function PrintBrokenString(const Rect: TRectangle; const Color: TCastleColor; const S: string; const LineSpacing: Integer; const AlignHorizontal: THorizontalPosition; const AlignVertical: TVerticalPosition): Integer;`
| `function PrintBrokenString(X0, Y0: Integer; const Color: TCastleColor; const S: string; const MaxLineWidth: Integer; const PositionsFirst: boolean; const LineSpacing: Integer): Integer;`
| `function PrintBrokenString(const S: string; const MaxLineWidth, X0, Y0: Integer; const PositionsFirst: boolean; const LineSpacing: Integer): Integer; deprecated;`
| `procedure PushProperties;`
| `procedure PopProperties;`
### Properties
| `property Scale: Single read FScale write SetScale;`
| `property Size: Single read GetSize write SetSize;`
| `property Outline: Cardinal read FOutline write FOutline;`
| `property OutlineColor: TCastleColor read FOutlineColor write FOutlineColor;`
## Description ### Methods
| `constructor Create;`
| `destructor Destroy; override;`
| `procedure PrintAndMove(const s: string); deprecated;`
Warning: this symbol is deprecated. 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.
| `procedure Print(const X, Y: Integer; 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.
| `procedure Print(const Pos: TVector2Integer; const Color: TCastleColor; const S: string); overload;`
| `procedure Print(const X, Y: Integer; const S: string); overload; deprecated;`
Warning: this symbol is deprecated.
| `procedure Print(const s: string); overload; deprecated;`
Warning: this symbol is deprecated.
| `procedure PrintRect(const Rect: TRectangle; const Color: TCastleColor; const S: string; const HorizontalAlignment: THorizontalPosition; const VerticalAlignment: TVerticalPosition);`
Print text, aligning within given rectangle. Hint: Use TRectangle.Grow(-10) or similar to align within a rectangle with padding.
| `procedure PrintRectMultiline(const Rect: TRectangle; const Color: TCastleColor; const S: string; const HorizontalAlignment: THorizontalPosition; const VerticalAlignment: TVerticalPosition; const Tags: boolean; const LineSpacing: Integer; const TextHorizontalAlignment: THorizontalPosition = hpLeft);`
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 Tags, LineSpacing, TextHorizontalAlignment.
| `procedure GLContextOpen; virtual;`
The font may require some OpenGL resources for drawing. You can explicitly create them using `GLContextOpen` (although it is never needed) and explicitly destroy them (although it is needed only in some situations). You can explicitly create resources using `GLContextOpen`. It's always optional to call `GLContextOpen`, resources will be automatically created anyway in the nearest Print call. Note that only the PrintXxx methods require an OpenGL context, the rest of the methods (like measuring the text sizes) may be used at any time, even before initializing the OpenGL context. You can also explicitly release the OpenGL resources using GLContextClose. This is required if you want to keep the TCastleFont instance existing even after OpenGL context is closed. It is automatically done at destruction, so you do not have to worry about it if you want to destroy TCastleFont instance before closing OpenGL context. Calling GLContextClose is also automatically taken care of if you use this font as CastleControls.UIFont, CastleControls.UIFontSmall or TUIControlFont.CustomFont or TCastleTheme.MessageFont.
| `procedure GLContextClose; virtual;`
| `function TextWidth(const S: string): Integer; virtual; abstract;`
| `function TextHeight(const S: string): Integer; virtual; abstract;`
| `function TextHeightBase(const S: string): Integer; 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).
| `function TextMove(const S: string): TVector2Integer; virtual; abstract;`
| `function TextSize(const S: string): TVector2Integer;`
| `function RowHeight: Integer;`
Height of a row of text in this font. This may be calculated as simply `TextHeight('Wy')` for most normal fonts.
| `function RowHeightBase: Integer;`
Height (above the baseline) of a row of text in this font. Similar to TextHeightBase and TextHeight, note that `RowHeightBase` is generally smaller than RowHeight, because `RowHeightBase` doesn't care how low the letter may go below the baseline.
| `function Descend: Integer;`
How low the text may go below the baseline.
| `procedure BreakLines(const unbroken: string; broken: TStrings; MaxLineWidth: integer); 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).
| `procedure BreakLines(unbroken, broken: TStrings; MaxLineWidth: integer); overload;`
| `procedure BreakLines(broken: TStrings; MaxLineWidth: Integer; FirstToBreak: integer); overload;`
| `function MaxTextWidth(SList: TStrings; const Tags: boolean = false): Integer;`
Largest width of the line of text in given list. ###### Parameters Tags Indicates that strings inside SList use HTML-like tags, the same as interpreted by PrintStrings. If your SList uses these tags (for example, you plan to call later PrintStrings with the same SList and Tags = `True`) then make sure you pass Tags = `True` to this method. Otherwise, `MaxTextWidth` will treat tags text (like `<font ...>`) like a normal text, usually making the width incorrectly large.
| `procedure PrintStrings(const X0, Y0: Integer; const Color: TCastleColor; const Strs: TStrings; const Tags: boolean; const LineSpacing: Integer; 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. LineSpacing Extra space between lines. Distance between each line is determined by RowHeight + 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 (RowHeight + LineSpacing) is > 0. Tags Enable some HTML-like tags to mark font changes inside the text. For now, these can only be used to surround whole lines (so you have to place opening tag at the beginnig of line, and closing tag at the end of line). For now, the only tag handled is `<font color="#rrggbb">` that changes line color to specified RGB. Also, we handle `<font color="#rrggbbaa">` where the last component is alpha (opacity), and when it's < 1 then we render using blending. Close with `</font>`. This functionality may be enhanced in the future (feature requests and patches welcome). Don't expect full HTML implementation inside, but some small set of useful tags may be doable and comfortable to use. Not necessarily replicating some (old version of) HTML standard. 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.
| `procedure PrintStrings(const Strs: TStrings; const Tags: boolean; const LineSpacing: Integer; const X0: Integer = 0; const Y0: Integer = 0); overload; deprecated;`
Warning: this symbol is deprecated.
| `procedure PrintStrings(const Strs: array of string; const Tags: boolean; const LineSpacing: Integer; const X0: Integer = 0; const Y0: Integer = 0); overload; deprecated;`
Warning: this symbol is deprecated.
| `function PrintBrokenString(const Rect: TRectangle; const Color: TCastleColor; const S: string; const LineSpacing: Integer; const AlignHorizontal: THorizontalPosition; const AlignVertical: TVerticalPosition): Integer;`
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 (with Tags = always false for now, since our string breaking cannot omit tags). 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 (RowHeight + 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.
| `function PrintBrokenString(X0, Y0: Integer; const Color: TCastleColor; const S: string; const MaxLineWidth: Integer; const PositionsFirst: boolean; const LineSpacing: Integer): Integer;`
| `function PrintBrokenString(const S: string; const MaxLineWidth, X0, Y0: Integer; const PositionsFirst: boolean; const LineSpacing: Integer): Integer; deprecated;`
Warning: this symbol is deprecated.
| `procedure PushProperties;`
Save draw properties to a stack. Saves: Scale (synchronized with Size), Outline, OutlineColor.
| `procedure PopProperties;`
### Properties
| `property Scale: Single read FScale write SetScale;`
| `property Size: Single read GetSize write SetSize;`
Adjust font size by scaling. Underneath, it scales the font using Scale property, to adjust it to requested size.
| `property Outline: Cardinal read FOutline write FOutline;`
`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).
| `property OutlineColor: TCastleColor read FOutlineColor write FOutlineColor;`
Outline color, used only if Outline <> 0. Default is black.
Generated by PasDoc 0.13.0 on 2015-06-15 04:43:09