ImgAddSize - ProGUI Reference Manual

Syntax

Success = ImgAddSize(Img, SrcImg, DPI=#Null)

Description

Adds an alternative size or DPI-specific representation (SrcImg) to an existing ProGUI image object (Img). This allows ProGUI's rendering system to automatically select the most appropriate image variant from the available alternatives when drawing the base image (Img) at different scaled sizes or display DPIs, improving quality and performance.

Parameters

Img
The handle of the base ProGUI image object to which the alternative variant will be added.

SrcImg
The handle of the ProGUI image object representing the alternative size or DPI variant.

DPI (optional)
The specific Dots Per Inch (DPI) value this alternative image is designed for (e.g., 96, 144, 192). If specified, the image is registered as a direct DPI substitute. Default is #Null.

Return Value

Returns #True if the alternative size or DPI variant was successfully added or updated. Returns #False if either handle is invalid, if Img and SrcImg are the same, or if no modifications were actually made (e.g., identical size variant already exists and wasn’t overwritten).

Remarks

When DrawImg() or an image brush is used, ProGUI checks the target rendering size (considering DPI scaling) and selects the variant from Img's internal list (including the base Img itself and any added via ImgAddSize).

If DPI is specified and the image property #PG_Img_SnapToDPI is enabled via ImgSetProperty(), ProGUI will automatically swap to the variant matching the active monitor or drawing DPI.

If #PG_Img_SnapToSize is enabled, ProGUI will select the variant that has the closest dimensions greater than or equal to the target size. If no larger size is available, the largest available variant is used.

This is particularly useful for loading multi-size icon files (.ico) or supporting high-DPI (Retina) displays. You can load the base size as Img and then add the larger/higher-DPI sizes using ImgAddSize().

ProGUI increments the reference count of SrcImg when it's added. You should still call FreeImg() on your handle to SrcImg after adding it; the image data will persist as long as the base Img holds a reference. If a variant with the exact dimensions or DPI already exists for Img, the existing variant's image handle will be replaced (and its reference count decremented) with SrcImg. The internal lists of alternate sizes are kept sorted automatically.

Examples

IncludeFile "ProGUI_PB.pbi"

StartProGUI()

; Assume the png images exist
Global BaseIcon = LoadImg("Icons\testMultiIcon\testMultiIcon2-13.png") ; 16 x 16
Icon32 = LoadImg("Icons\testMultiIcon\testMultiIcon2-12.png") ; 32 x 32
Icon64 = LoadImg("Icons\testMultiIcon\testMultiIcon2-11.png") ; 64 x 64

Procedure DrawHandler(Widget, EventType, *EventData.PG_EventDraw)
  ; Draw the base icon at different sizes. ProGUI selects the best variant.
  DrawImg(BaseIcon, 10, 10, 16, 16)  ; Should use 16x16
  DrawImg(BaseIcon, 40, 10, 24, 24)  ; Should use 32x32 (closest >=)
  DrawImg(BaseIcon, 80, 10, 32, 32)  ; Should use 32x32
  DrawImg(BaseIcon, 130, 10, 48, 48) ; Should use 64x64 (closest >=)
  DrawImg(BaseIcon, 200, 10, 64, 64) ; Should use 64x64
  DrawImg(BaseIcon, 280, 10, 96, 96) ; Should use 64x64 (largest available)
EndProcedure

If BaseIcon And Icon32 And Icon64
  Debug "Base icon (16x16) loaded."

  ; Add the larger sizes as variants
  If ImgAddSize(BaseIcon, Icon32)
    Debug "Added 32x32 variant."
  EndIf
  If ImgAddSize(BaseIcon, Icon64)
    Debug "Added 64x64 variant."
  EndIf

  ; Now you only need to keep track of BaseIcon. ProGUI will pick the best size when drawing.
  MyWindow = CreateWindow(0, 0, 400, 200, "Multi-Size Image")
  If MyWindow
    
    LayoutSetPadding(#Null, 20)
    Widget = CreateWidget(0,0,400,400) ; Create a widget to draw on
    AddEventHandler(Widget, #PG_Event_Draw, @DrawHandler())
    WindowShow(MyWindow, #True, #PG_WindowShow_ScreenCentered)

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

  ; Free your references. The image data might still be held by BaseIcon.
  FreeImg(Icon32)
  FreeImg(Icon64)
  FreeImg(BaseIcon) ; This will free all variants if ref count reaches 0

Else
  Debug "Error loading one or more icons."
  If BaseIcon : FreeImg(BaseIcon) : EndIf
  If Icon32 : FreeImg(Icon32) : EndIf
  If Icon64 : FreeImg(Icon64) : EndIf
EndIf

StopProGUI()

IncludeFile "ProGUI_PB.pbi"

StartProGUI()

; Load base icon and its high-DPI variants
Global BaseIcon = LoadImg("Icons\testMultiIcon\testMultiIcon2-13.png")  ; 16 x 16, 96 DPI (100%)
Icon144 = LoadImg("Icons\testMultiIcon\testMultiIcon2-12.png")          ; 32 x 32, 144 DPI (150%)
Icon192 = LoadImg("Icons\testMultiIcon\testMultiIcon2-11.png")          ; 64 x 64, 192 DPI (200%)

; Define a draw handler
Procedure DrawHandler(Widget, EventType, *EventData.PG_EventDraw)
  ; Draw the base icon. 
  ; If you drag this window to a 150% scaled monitor, it automatically draws Icon144!
  DrawImg(BaseIcon, 10, 10)  
EndProcedure

If BaseIcon And Icon144 And Icon192
  Debug "Base icon loaded."

  ; Add the larger sizes as DPI variants
  If ImgAddSize(BaseIcon, Icon144, 144)
    Debug "Added 150% DPI variant."
  EndIf
  If ImgAddSize(BaseIcon, Icon192, 192)
    Debug "Added 200% DPI variant."
  EndIf

  ; Instruct ProGUI to snap to the exact DPI representations
  ImgSetProperty(BaseIcon, #PG_Img_SnapToDPI, #True)

  ; Now you only need to keep track of BaseIcon. ProGUI will pick the best DPI variant when drawing.
  MyWindow = CreateWindow(0, 0, 400, 200, "Multi-DPI Image")
  If MyWindow
      
    LayoutSetPadding(#Null, 20)
    Widget = CreateWidget(0,0,400,400) ; Create a widget to draw on
    AddEventHandler(Widget, #PG_Event_Draw, @DrawHandler())
    WindowShow(MyWindow, #True, #PG_WindowShow_ScreenCentered)

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

  ; Free your references. The image data might still be held by BaseIcon.
  FreeImg(Icon144)
  FreeImg(Icon192)
  FreeImg(BaseIcon) ; This will free all variants since its ref count reaches 0

Else
  Debug "Error loading one or more icons."
  If BaseIcon : FreeImg(BaseIcon) : EndIf
  If Icon144  : FreeImg(Icon144)  : EndIf
  If Icon192  : FreeImg(Icon192)  : EndIf
EndIf

StopProGUI()

Supported OS

Windows, Linux