CreateText - ProGUI Reference Manual

Syntax

Text = CreateText(Content$, FontName$="", FontSize.d=#Null, LayoutWidth.d=#Null, LayoutHeight.d=#Null, isFontSizeDIP.b=#False)

Description

Creates a new text object containing the specified content, font, and layout properties. This object can then be manipulated, styled, and drawn onto an output target using DrawTxt or DrawTxtFill.

Parameters

Content$
The initial text string to be rendered.

FontName$ (optional)
The name of the font family to use (e.g., “Arial”, “Tahoma”). If left empty (""), it automatically defaults to the system’s default UI font.

FontSize.d (optional)
The size of the font. If set to #Null, it defaults to the system’s default font size.

LayoutWidth.d (optional)
The maximum width of the text layout in device-independent pixels (DIPs). This boundary is used for word wrapping and alignment calculations. Default is #Null (unrestricted width).

LayoutHeight.d (optional)
The maximum height of the text layout in DIPs. This is used for vertical alignment and trimming. Default is #Null (unrestricted height).

isFontSizeDIP.b (optional)
Determines how the FontSize value is interpreted. If #False (the default), FontSize is treated as standard typographical points (pt). If #True, FontSize is interpreted as device-independent pixels (DIPs) and is automatically converted internally.

Return Value

Returns a handle to the newly created text object. Returns #Null or #False if the creation failed.

Remarks

A text object encapsulates not just the string itself, but also its formatting (weight, style, alignment) and layout box constraints. When you are finished using a text object, you must release its resources by calling FreeText().

Newly created text objects default to normal font weight (#PG_Text_Weight_Normal) and no word wrapping (#PG_Text_Wrap_None). These properties can be subsequently modified using the various TextSet*() commands.

Example

IncludeFile "ProGUI_PB.pbi"

StartProGUI()

; Create a text object with specific font, size, and layout bounds
Global MyText = CreateText("Welcome to ProGUI text rendering! This text will wrap within the 200 DIP layout width.", "Arial", 16, 200, 150)

; Enable word wrapping and center alignment on the created text object
TextSetWrap(MyText, #PG_Text_Wrap_Wrap)
TextSetAlign(MyText, #PG_Text_Align_Center)
TextSetJustify(MyText, #PG_Text_Justify_Center)

Procedure DrawHandler(Window, EventType, *EventData.PG_EventDraw, *UserData)
  
    DrawClear(RGB(240, 240, 240), 1)

    ; Draw the layout boundary box for visualization
    DrawBoxStroke(50, 50, 200, 150, RGB(255, 0, 0))

    ; Draw the text object inside its layout constraints
    DrawTxt(MyText, 50, 50, RGB(0, 0, 0))

EndProcedure

MyWindow = CreateWindow(0, 0, 300, 250, "CreateText Example")

If MyWindow
  AddEventHandler(MyWindow, #PG_Event_Draw, @DrawHandler())
  WindowShow(MyWindow, #True, #PG_WindowShow_ScreenCentered)

  Repeat
    Event = WaitWindowEvent()
  Until Event = #PB_Event_CloseWindow
EndIf

; Clean up the text object resources
FreeText(MyText)

StopProGUI()

Supported OS

Windows, Linux