CreateWidget - ProGUI Reference Manual

Syntax

Widget = CreateWidget(x, y, Width, Height, *UserData=#Null, Flags=#Null)

Description

Creates a new standard ProGUI widget. Standard widgets are rendered entirely by ProGUI using its drawing commands and are highly customizable through skinning and event handlers. They are added to the current layout (see LayoutSetCurrent()).

Parameters

x
The initial horizontal position of the widget relative to its parent layout container (in DIPs). Primarily used by Basic layouts; Flex and Grid layouts override this based on their rules.

y
The initial vertical position of the widget relative to its parent layout container (in DIPs). Primarily used by Basic layouts; Flex and Grid layouts override this based on their rules.

Width
The initial ideal width of the widget (in DIPs). Layout engines may adjust this based on available space and other item properties. Use #PG_Widget_FitContent to automatically size based on content (e.g., a child layout's overflow).

Height
The initial ideal height of the widget (in DIPs). Layout engines may adjust this based on available space and other item properties. Use #PG_Widget_FitContent to automatically size based on content.

*UserData (optional)
A pointer to any user-defined data to associate with the widget. Can be retrieved later using WidgetGetUserData(). Default is #Null.

Flags (optional)
A combination of flags to customize the widget's initial state and behavior. Default is #Null.

#PG_Widget_Hide        : Creates the widget initially hidden (equivalent to calling WidgetShow(Widget, #PG_Widget_Hide) later).
#PG_Widget_NoDraw      : Creates the widget initially invisible but still participating in layout (equivalent to WidgetShow(Widget, #PG_Widget_NoDraw)).
#PG_Widget_NoMouse     : Creates the widget initially ignoring mouse events.
#PG_Widget_LayoutBasic : Automatically creates and assigns a Basic layout to this widget.
#PG_Widget_LayoutFlex  : Automatically creates and assigns a Flexbox layout to this widget.
#PG_Widget_LayoutGrid  : Automatically creates and assigns a Grid layout to this widget.

Note: Custom user flags can be defined starting from #PG_Widget_FirstUserFlag.

Return Value

Returns a handle to the newly created widget object if successful, or #Null if creation failed. This handle is used in subsequent widget-related commands.

Remarks

Widgets created with this function need a drawing callback attached via AddEventHandler() and the #PG_Event_Draw event to render anything. The widget is added to the layout container currently set as active by LayoutSetCurrent() or obtained via WindowGetLayout() or WidgetGetLayout(). The initial (x, y) coordinates are only relevant for Basic layouts. The `Width` and `Height` parameters set the `idealWidth` and `idealHeight` properties of the underlying layout item.

Example

IncludeFile "ProGUI_PB.pbi"

StartProGUI()

Global UserDataString$

; Custom draw procedure for our widget
Procedure DrawMyWidget(Widget, EventType, *EventData.PG_EventDraw, *UserData)
  ; Get background color from skin (assuming "mywidget" class is defined)
  WidgetGetSkinColor(Widget, "", "background-color", @bgColor.l, @bgOpacity.f)
  If bgColor = 0 ; Default if not found in skin
      bgColor = RGB(200, 200, 200)
      bgOpacity = 1.0
  EndIf

  DrawBox(0, 0, *EventData\width, *EventData\height, bgColor, bgOpacity)
  DrawBoxStroke(0, 0, *EventData\width, *EventData\height, RGB(50, 50, 50), 0.8)

  ; Retrieve and display widget user data if it exists
  *widgetUserData = WidgetGetUserData(Widget)
  If *widgetUserData
    MyText$ = PeekS(*widgetUserData)
    Static MyTextObj ; Static text object for efficiency
    If MyTextObj = 0
        MyTextObj = CreateText("", "Arial", 12)
        TextSetAlign(MyTextObj, #PG_Text_Align_Center)
        TextSetJustify(MyTextObj, #PG_Text_Justify_Center)
    EndIf
    TextSetContent(MyTextObj, MyText$)
    TextSetWidth(MyTextObj, *EventData\width - 10) ; Add padding
    TextSetHeight(MyTextObj, *EventData\height - 10)
    DrawTxt(MyTextObj, 5, 5, RGB(0,0,0), 1)
  EndIf
EndProcedure

MyWindow = CreateWindow(0, 0, 400, 300, "CreateWidget Example")
RootLayout = WindowGetLayout(MyWindow)
LayoutSetType(RootLayout, #PG_Layout_Type_Flex) ; Use Flex layout
LayoutSetPadding(RootLayout, 10)

If MyWindow
  ; Create a widget with UserData
  UserDataString$ = "Widget 1"
  Widget1 = CreateWidget(0, 0, 150, 50, @UserDataString$)
  WidgetSetClass(Widget1, "mywidget") ; Assign a class for skinning
  WidgetSetMargin(Widget1, 5)
  AddEventHandler(Widget1, #PG_Event_Draw, @DrawMyWidget())
  
  ; Set the background-color skin property for "mywidget"
  SkinSetValue("mywidget", "", "", "background-color", "red")

  ; Create another widget, automatically giving it a child Flex layout
  Widget2 = CreateWidget(0, 0, 100, 80, #Null, #PG_Widget_LayoutFlex)
  WidgetSetClass(Widget2, "mywidget2")
  WidgetSetMargin(Widget2, 5)
  AddEventHandler(Widget2, #PG_Event_Draw, @DrawMyWidget())

  ; Add a sub-widget inside Widget2's layout
  LayoutSetCurrent(WidgetGetLayout(Widget2)) ; Set current layout to Widget2's layout
  SubWidget = CreateWidget(0, 0, 50, 20)
  WidgetSetClass(SubWidget, "button") ; Different class
  WidgetSetMargin(SubWidget, 10)
  ; (Add drawing handler for SubWidget if needed)
  LayoutSetCurrent(RootLayout) ; Restore current layout

  WindowShow(MyWindow, #True, #PG_Window_ScreenCentered)

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

StopProGUI()

Supported OS

Windows, Linux