CreateOsWidget - ProGUI Reference Manual

Syntax

Widget = CreateOsWidget(x, y, Width, Height, OS_ID)

Description

Creates a ProGUI widget that wraps an existing native operating system control (gadget). This allows integrating standard OS controls (like buttons, text inputs, listviews created with PureBasic's gadget commands or native API calls) into the ProGUI layout and rendering system. ProGUI attempts to capture the visual output of the OS control and render it within the ProGUI window.

Parameters

x
The initial horizontal position hint (in DIPs). Actual position is determined by the layout.

y
The initial vertical position hint (in DIPs). Actual position is determined by the layout.

Width
The initial ideal width of the widget (in DIPs). Use #PG_Widget_FitContent for automatic sizing if applicable.

Height
The initial ideal height of the widget (in DIPs). Use #PG_Widget_FitContent for automatic sizing if applicable.

OS_ID
The native operating system handle of the control to wrap. On Windows, this is the HWND obtained typically from `GadgetID()`. On Linux, it would be the corresponding GtkWidget pointer.

Return Value

Returns a handle to the newly created ProGUI wrapper widget object if successful, or #Null if creation failed (e.g., invalid OS_ID).

Remarks

This function is essential for using native controls within a ProGUI interface. ProGUI uses OS-specific techniques (like GDI interop or potentially graphics capture on Windows) to render the wrapped control. The wrapped control is reparented internally to a ProGUI container.

Not all OS controls might render perfectly, especially complex ones or those with non-standard drawing. Performance might vary depending on the control and the OS. The `x`, `y`, `Width`, and `Height` act as initial layout hints; the final size and position are managed by ProGUI's layout engine. Use standard ProGUI functions (WidgetSetWidth(), WidgetSetMargin(), etc.) to control the wrapper widget's layout properties.

Specific OS widget types like WebView2 (CreateWebView()) have dedicated creation functions for better integration.

Example

IncludeFile "ProGUI_PB.pbi"

StartProGUI()

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

If MyWindow
  ; Create a native PureBasic button first
  OSButton = ButtonGadget(#PB_Any, 0, 0, 0, 0, "Native Button")

  If OSButton
    ; Wrap the native button with a ProGUI OS Widget
    WrappedButton = CreateOsWidget(0, 0, 120, 30, GadgetID(OSButton))
    If WrappedButton
      WidgetSetMargin(WrappedButton, 5)
      Debug "Native Button wrapped successfully."
    Else
      Debug "Failed to wrap native button."
      ; Free the gadget if wrapping failed and it won't be used otherwise
      FreeGadget(OSButton)
    EndIf
  EndIf

  ; Create a native PureBasic StringGadget
  OSString = StringGadget(#PB_Any, 0, 0, 0, 0, "Native Input")
  If OSString
    WrappedString = CreateOsWidget(0, 0, 200, 25, GadgetID(OSString))
    If WrappedString
      WidgetSetMargin(WrappedString, 5)
      Debug "Native StringGadget wrapped successfully."
    Else
      Debug "Failed to wrap native StringGadget."
      FreeGadget(OSString)
    EndIf
  EndIf


  WindowShow(MyWindow, #True, #PG_Window_ScreenCentered)

  Repeat
    Event = WaitWindowEvent()

    If Event = #PB_Event_Gadget
        If EventGadget() = OSButton
            Debug "Native Button Clicked!"
        EndIf
    EndIf

  Until Event = #PB_Event_CloseWindow
EndIf

StopProGUI()

Supported OS

Windows, Linux (Support level may vary depending on the specific OS control)