CreateText - ProGUI Reference Manual

Syntax

Text = CreateText(Content$, FontName$, PointSize.d, LayoutWidth.d=#Null, LayoutHeight.d=#Null)

Description

Creates a new text object used for drawing formatted text. This object stores the text content, font information, and layout constraints.

Parameters

Content$
The initial string content for the text object.

FontName$
The name of the font family to use (e.g., "Arial", "Tahoma", "Segoe UI"). If "", a default system font (like the menu font) might be used.

PointSize.d
The desired font size in points (a standard typographic unit, where 72 points approximately equals one inch). ProGUI uses this size at the base 96 DPI and scales it accordingly for the current display DPI during rendering. If 0, a default system font size might be used.

LayoutWidth.d (optional)
The initial constraint for the maximum layout width in device-independent pixels (DIPs). This affects text wrapping and horizontal alignment/justification. Default is #Null (no explicit width constraint initially).

LayoutHeight.d (optional)
The initial constraint for the maximum layout height in DIPs. This affects vertical alignment and text trimming. Default is #Null (no explicit height constraint initially).

Return Value

Returns a handle to the newly created text object if successful, or #Null if creation failed (e.g., invalid font name, memory error).

Remarks

The created text object encapsulates the text string and its formatting properties. Subsequent calls to TextSet... functions modify this object. The object must be freed using FreeText() when no longer needed. The actual rendered size depends on the text content, font metrics, layout constraints, and the DPI of the drawing target.

Example

IncludeFile "ProGUI_PB.pbi"

StartProGUI()

MyWindow = CreateWindow(0, 0, 400, 200, "CreateText Example")

If MyWindow
  ; Create a basic text object
  Text1 = CreateText("Hello, World!", "Verdana", 16)

  ; Create another text object with layout constraints
  Text2 = CreateText("This text will wrap if the container is narrow enough.", "Arial", 10, 150) ; Max width 150 DIPs

  If Text1 And Text2
    Debug "Text objects created successfully."
    ; Use them for drawing, e.g., in a draw handler:
    ; DrawTxt(Text1, 10, 10, 0)
    ; DrawTxt(Text2, 10, 50, 0)
    FreeText(Text1)
    FreeText(Text2)
  Else
    Debug "Failed to create one or both text objects."
    If Text1 : FreeText(Text1) : EndIf
    If Text2 : FreeText(Text2) : EndIf
  EndIf

  WindowShow(MyWindow, #True, #PG_Window_ScreenCentered)
  Repeat : Event = WaitWindowEvent() : Until Event = #PB_Event_CloseWindow
EndIf

StopProGUI()

Supported OS

Windows, Linux