DrawSkinBackground - ProGUI Reference Manual

Syntax

Success = DrawSkinBackground(Widget, Component$, x.d, y.d, Width.d, Height.d)

Description

Draws the background layers defined in the skin for a specific widget and component state. This function interprets the complex `background` properties (like `background-image`, `background-color`, `background-position`, `background-size`, `background-repeat`, `background-opacity`, `background-attachment`) associated with the widget's current skin state and renders them within the specified area.

Parameters

Widget
The handle of the ProGUI widget whose background is to be drawn.

Component$
The name of the component part of the widget for which to draw the background (e.g., "", "thumb", "trackbar"). An empty string ("") refers to the main widget element.

x, y
The top-left coordinates (in DIPs relative to the current drawing target) where the background should be drawn.

Width, Height
The width and height (in DIPs) of the area to fill with the background.

Return Value

Returns #True if a background was defined and drawn (even if just a solid color), or #False if the widget handle was invalid or no background properties were found for the widget's current state and component in the skin.

Remarks

This function should typically be called within the widget's #PG_Event_Draw handler. It handles multiple background layers (images and gradients), positioning, sizing (including keywords like `cover` and `contain`), repeating, opacity, and attachment (`fixed`, `scroll`). It automatically fetches the background definition from the skin based on the widget's class, current state (set by WidgetSetSkinState()), and the specified component. It also integrates with the skin animation system to render transitions smoothly.

Example

IncludeFile "ProGUI_PB.pbi"

StartProGUI()

; Define some skin properties for a widget with class "myBackgroundWidget"
SkinSetValue("myBackgroundWidget", "", "", "background-color", "lightblue")
SkinSetValue("myBackgroundWidget", "", "", "background-image", "url('icons/boingball.png'), linear-gradient(to bottom, white, silver)")
SkinSetValue("myBackgroundWidget", "", "", "background-repeat", "no-repeat, repeat-x")
SkinSetValue("myBackgroundWidget", "", "", "background-position", "center, 0 0")
SkinSetValue("myBackgroundWidget", "", "", "background-size", "contain, auto 50px") ; Contain boingball, gradient is 50px high

SkinSetValue("myBackgroundWidget", "hover", "", "background-color", "lightgreen") ; Change color on hover
SkinSetValue("myBackgroundWidget", "", "", "transition", "background-color 1s") ; Animate color change

Procedure DrawBgWidget(Widget, EventType, *EventData.PG_EventDraw, *UserData)
  ; Draw the background defined in the skin for the main component ("")
  DrawSkinBackground(Widget, "", 0, 0, *EventData\width, *EventData\height)

  ; Optionally draw other things on top
  DrawBoxStroke(1, 1, *EventData\width-2, *EventData\height-2, RGB(0,0,0), 0.5)
EndProcedure

Procedure MouseBgWidget(Widget, EventType, *EventData.PG_EventMouse)
  Select EventType
    Case #PG_Event_MouseEnter
      WidgetSetSkinState(Widget, "hover")
    Case #PG_Event_MouseLeave
      WidgetSetSkinState(Widget, "")
  EndSelect
EndProcedure

MyWindow = CreateWindow(0, 0, 400, 300, "DrawSkinBackground Example")
RootLayout = WindowGetLayout(MyWindow)
LayoutSetPadding(RootLayout, 10)

If MyWindow
  BgWidget = CreateWidget(0, 0, 0, 0)
  WidgetSetMinWidth(BgWidget, 100)
  WidgetSetMinHeight(BgWidget, 100)
  WidgetSetClass(BgWidget, "myBackgroundWidget") ; Assign class for skinning
  AddEventHandler(BgWidget, #PG_Event_Draw, @DrawBgWidget())
  AddEventHandler(BgWidget, #PG_Event_MouseEnter, @MouseBgWidget())
  AddEventHandler(BgWidget, #PG_Event_MouseLeave, @MouseBgWidget())

  WindowShow(MyWindow, #True, #PG_Window_ScreenCentered)

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

StopProGUI()

Supported OS

Windows, Linux