GFx::DrawTextManager

The DrawTextManager class instance manages instances of DrawText class; it creates, renders and measures text extents.

There are several ways of creating the DrawTextManager class instance:

DrawTextManager();

A default constructor. Will create internal instances of font, resource library and log. A system font provider should be used as font source (method SetFontProvider).

Example:

Ptr<GFx::DrawTextManager> pDm1 = *new DrawTextManager();
DrawTextManager(MovieDef* pmovieDef);

This constructor takes a pointer to MovieDef as a parameter. The instance of the DrawTextManager inherits all states from the passed MovieDef instance, including font, font providers, etc. All fonts being contained in the MovieDef instance become accessible for the DrawTextManager (and by all DrawText instances created by this DrawTextManager).

Example:
```
Ptr<GFx::MovieDef> pmovieDef = *mLoader.CreateMovie("drawtext_fonts.swf", Loader::LoadAll);
Ptr<GFx::DrawTextManager> pDm2 = *new DrawTextManager(pmovieDef);
```
DrawTextManager(GFx::Loader* ploader);

This constructor takes a pointer to GFx::Loader as a parameter and inherits all the states set on the loader including the font library.

Example:
```
GFx::Loader mLoader;
..
Ptr<GFx::DrawTextManager> pDm1 = *new DrawTextManager(&mLoader);
```

Creating GFx::DrawText.

There are several methods to create DrawText instances in DrawTextManager class. One instance of DrawTextManager can be used to create as many DrawText instances as necessary.

*   DrawText* CreateText(const char* putf8Str, const RectF& viewRect, const TextParams* ptxtParams = NULL, unsigned depth = ~0u);
*   DrawText* CreateText(const wchar_t* pwstr, const RectF& viewRect, const TextParams* ptxtParams = NULL, unsigned depth = ~0u);
*   DrawText* CreateText(const String& str, const RectF& viewRect, const TextParams* ptxtParams = NULL, unsigned depth = ~0u);

The methods above create DrawText instances using plain text (null-terminated UTF-8 string, null-terminated Unicode/UCS-2 and Scaleform::String respectively).

putf8str : specifies a null-terminated UTF-8 string.
pwstr : specifies a null–terminated Unicode/UCS-2 string.
str: specifies a Scaleform::String.
depth: Specifies the order of drawing.
viewRect : specifies coordinates of text view area (in pixels), relatively to top-left corner of viewport (see BeginDisplay).

ptxtParams : Optional parameter. It specifies parameters of newly created text. TextParams has the following structure:

struct TextParams
{
    ColorTextColor;
    DrawText::Alignment  HAlignment;
    DrawText::VAlignment VAlignment;
    DrawText::FontStyle  FontStyle;
    floatFontSize;
    String   FontName;
    bool Underline;
    bool Multiline;
    bool WordWrap;
};

TextColor : specifies the color of the text, including the alpha channel.
HAlignment: specifies horizontal alignment. Possible values are: DrawText::Align_Left (default), DrawText::Align_Right, DrawText::Align_Center, DrawText::Align_Justify.
VAlignment : specifies vertical alignment.Possible values are: DrawText::VAlign_Top (default), DrawText::VAlign_Bottom, DrawText::VAlign_Center.
FontStyle : specifies font style, such as bold, italic, normal or bolditalic. Possible values are: DrawText::Normal, DrawText::Bold, DrawText::Italic, DrawText::BoldItalic (and DrawText::ItalicBold as a synonym).
FontSize: specifies size of font, in pixels. May be fractional.
FontName: specifies name of the font, for example “Arial”, “Times New Roman”. Do not put “Bold” or “Italic” suffixes in name; use FontStyle instead.
Underline: specifies whether underline should be used or not.
Multiline: toggles multiline/singleline modes for the text.
WordWrap: turns on/off wordwrapping; it is meaningful only for multiline text boxes.

If ptxtParams optional parameter is not specified then DrawTextManager uses default text parameters. It is possible to set and get these default text parameters by using the following methods:

  void SetDefaultTextParams(const TextParams& params);
  const TextParams& GetDefaultTextParams() const;

The following DrawTextManager’s methods – CreateHtmlText - are similar to CreateText ones described above, but they create the DrawText instances from HTML:

 // Creates and initialize a DrawText object using specified HTML.
DrawText* CreateHtmlText(const char* putf8Str, const RectF& viewRect, const TextParams* ptxtParams = NULL,
                                unsigned depth = ~0u);
DrawText* CreateHtmlText(const wchar_t* pwstr, const RectF& viewRect, const TextParams* ptxtParams = NULL,
        unsigned depth = ~0u);
DrawText* CreateHtmlText(const String& str, const RectF& viewRect, const TextParams* ptxtParams = NULL,
        unsigned depth = ~0u);

Examples:

 // Creation of DrawText object using plain text with parameters.
String str("String No 2");
DrawTextManager::TextParams params;
params.FontName   = "Symbol";
params.FontSize   = 30;
params.FontStyle  = DrawText::Italic;
params.Multiline  = false;
params.HAlignment = DrawText::Align_Right;
params.VAlignment = DrawText::VAlign_Bottom;

Ptr<DrawText> ptxt;
ptxt = *pdm->CreateText(str, RectF(20, 300, 400, 700), &params);

// Creation of DrawText object from HTML.
Ptr<DrawText> ptxt;
ptxt = *pdm->CreateHtmlText("<p><FONT size='20'>AB
  <b>singleline</b><i> CD</i>O",
   RectF(20, 300, 400, 700));

Text Rendering

Text rendering is done in a way similar to rendering GFx::Movie. It is necessary to obtain DisplayHandle (GFx::DrawTextManager) and set the viewport (DrawTextManager::SetViewport). Please refer to GFx documentation for the details about Viewport.

Measuring Text Extents

DrawTextManager provides functionality to measure text rectangle dimensions required to render the text:

SizeF GetTextExtent(const char* putf8Str, float width = 0, const TextParams* ptxtParams = 0);
SizeF GetTextExtent(const wchar_t* pwstr, float width = 0, const TextParams* ptxtParams = 0);
SizeF GetTextExtent(const String& str, float width = 0,  const TextParams* ptxtParams = 0);

SizeF GetHtmlTextExtent(const char* putf8Str, float width = 0, const TextParams* ptxtParams = 0);
SizeF GetHtmlTextExtent(const wchar_t* pwstr, float width = 0, const TextParams* ptxtParams = 0);
SizeF GetHtmlTextExtent(const String& str, float width = 0, const TextParams* ptxtParams = 0);

GetTextExtent method calculates dimensions of text rectangle using plain text and, optionally, using TextParams and desired width of text.

GetHtmlTextExtent method calculates dimensions of text rectangle using HTML text and, optionally, using TextParams and desired width of text.

The optional ‘width’ parameter specifies desired width of text rectangle in the case when multiline and word wrapping are used. In this case, only the height of text rectangle will be calculated.

The optional ptxtParams specifies text parameters, which will be used during text dimensions measurement. If it is not specified then the default text parameters will be used (see SetDefaultTextParams / GetDefaultTextParams). For HTML version, the ptxtParams parameter works a set of default text parameters, so, all styles from parsed HTML virtually will be applied above the styles from the ‘ptxtParams’.

Examples:

 // Plain text extents
String str("String No 2");
DrawTextManager::TextParams params;
params.FontName   = "Symbol";
params.FontSize   = 30;
params.FontStyle  = DrawText::Italic;
params.Multiline  = false;
params.HAlignment = DrawText::Align_Right;
params.VAlignment = DrawText::VAlign_Bottom;

SizeF sz = pdm->GetTextExtent(str, 0, params);

params.WordWrap  = true;
params.Multiline = true;
sz = pdm->GetTextExtent(str, 120, params);

// HTML text extents
const wchar_t* html =  L"<p><FONT size='20'>AB <b>singleline</b><i> CD</i>O";
sz = pdm->GetHtmlTextExtent(html);

sz = pdm->GetHtmlTextExtent(html, 150);

GFx::DrawTextManager

Creating GFx::DrawText.

Text Rendering

Measuring Text Extents

Parent topic