ImgSetProperty - ProGUI Reference Manual

Syntax

Success = ImgSetProperty(Img, Property, Value)

Description

Sets specific behavioral properties for an image object. This is primarily used to control how the image selects among its alternate resolutions (added via ImgAddSize()) when being rendered or scaled.

Parameters

Img
The handle of the image object to modify.

Property
The property constant to set. Can be one of the following:

#PG_Img_SnapToSize : Forces the image to snap to the nearest available alternate size (based on explicit width/height) when scaled during drawing operations like `DrawImg()`.
#PG_Img_SnapToDPI  : Forces the image to snap to the best matching alternate size based on the current drawing context's DPI (Dots Per Inch) scaling.

Value
A boolean value (#True or #False) indicating whether to enable or disable the specified property.

Return Value

Returns #True if the property was successfully set, or #False if the image handle is invalid or the property constant is unrecognized.

Remarks

The #PG_Img_SnapToSize and #PG_Img_SnapToDPI properties are mutually exclusive. Enabling #PG_Img_SnapToSize automatically disables #PG_Img_SnapToDPI, and vice versa.

These properties are highly useful for responsive user interfaces where you want to provide multiple crisp resolution variants for an icon or graphic (using ImgAddSize()). By enabling one of these snap properties, ProGUI’s rendering engine will automatically swap to the cleanest underlying pixel data matching either the requested render bounds or the monitor’s DPI scaling factor, avoiding the blurriness associated with standard bitmap interpolation.

Example

IncludeFile "ProGUI_PB.pbi"

StartProGUI()

; Load a base image and a high-resolution alternate version
Global MyImage = LoadImg("Icons\testMultiIcon\testMultiIcon2-11.png")     ; 32 x 32
Global HighResImage = LoadImg("Icons\testMultiIcon\testMultiIcon2-6.png") ; 128 x 128

If MyImage And HighResImage
  ; Add the high-res image as an alternate size representation to the base image
  ImgAddSize(MyImage, HighResImage)
  
  FreeImg(HighResImage) ; We no longer need it

  ; Instruct the rendering engine to automatically snap to the best 
  ; available alternate size when the image is scaled up or down.
  ImgSetProperty(MyImage, #PG_Img_SnapToSize, #True)
EndIf

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

    ; Draw the image at its natural size (32x32)
    DrawImg(MyImage, 20, 20)

    ; Draw the image scaled up to 128x128.
    ; Because #PG_Img_SnapToSize is active, ProGUI will seamlessly use 
    ; the pixel data from 'HighResImage' to keep the rendering crisp.
    DrawImg(MyImage, 20, 80, 100, 100) ; notice 100 x 100 dimensions, the image is "snapped" to the nearest size which is rendered at 128 x 128

EndProcedure

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

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

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

FreeImg(MyImage)

StopProGUI()

Supported OS

Windows, Linux