LoadImg - ProGUI Reference Manual

Syntax

Img = LoadImg(Path$, Flags=#Null)

Description

Loads an image from the specified file path. The command supports standard image formats (like PNG, JPG) and icon files (.ico). It also features a powerful syntax for loading multi-resolution images (alternate sizes for DPI scaling) and applying operations via string commands appended to the path.

Parameters

Path$
The file path to the image to load.

Multi-resolution & String Commands: You can specify multiple image paths separated by semicolons (;) to load alternate resolutions for DPI scaling. ProGUI will automatically select the best fit depending on the window’s DPI (or the dimensions specified in DrawImg / Img Brushes). The final semicolon-separated segment can optionally contain space-separated text commands:

"snaptosize": Equivalent to the #PG_Img_SnapToSize flag.
"snaptodpi": Equivalent to the #PG_Img_SnapToDPI flag.
"trim": Equivalent to the #PG_Img_Trim flag.

Example: "icons/img_96.png; icons/img_120.png; snaptodpi trim"

Flags (optional)
A combination of flags modifying the image loading and rendering behavior. Default is #Null.

#PG_Img_SnapToSize : Instructs drawing commands to automatically snap to the nearest loaded alternate image size rather than scaling the base image.
#PG_Img_SnapToDPI  : Instructs drawing commands to automatically snap to the nearest loaded alternate image based on the current context's DPI.
#PG_Img_Trim       : Automatically crops fully transparent pixels from the edges of the image upon loading.

Return Value

Returns a handle to the newly created image object. Returns #Null (or 0) if the image file could not be found or loaded.

Remarks

When dealing with high-DPI displays, loading multi-resolution images and using the #PG_Img_SnapToDPI (or "snaptodpi") flag ensures that ProGUI uses the crispest version of your graphics without algorithmic blurring. Semicolon paths for alternate images that lack a directory will automatically use the directory of the base image path.

For icon (.ico) files, ProGUI automatically attempts to load the best matching bit-depth variations stored within the file to use as alternate sizes.

Example

IncludeFile "ProGUI_PB.pbi"

StartProGUI()

; Example 1: Basic image loading
Global SimpleImg = LoadImg("graphics/logo.png")

; Example 2: Loading an image with multi-resolution files and string commands
; This will load icon_96.png as the base, add icon_120.png and icon_144.png as alt sizes,
; and apply the SnapToDPI and Trim flags automatically.
Global MultiDpiImg = LoadImg("icons/icon_96.png; icon_120.png; icon_144.png; snaptodpi trim")

; Example 3: Using programmatic flags
Global TrimmedImg = LoadImg("graphics/character.png", #PG_Img_Trim)

Procedure DrawHandler(Window, EventType, *EventData.PG_EventDraw, *UserData)
    DrawClear(RGB(240, 240, 240), 1)
    
    If SimpleImg
        DrawImg(SimpleImg, 20, 20)
    EndIf
    
    If MultiDpiImg
        ; Will automatically pick the 120 or 144 version if the window is moved to a high-DPI monitor
        DrawImg(MultiDpiImg, 20, 100) 
    EndIf
EndProcedure

MyWindow = CreateWindow(0, 0, 400, 300, "LoadImg Example")

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

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

; Always free your images when done!
If SimpleImg : FreeImg(SimpleImg) : EndIf
If MultiDpiImg : FreeImg(MultiDpiImg) : EndIf
If TrimmedImg : FreeImg(TrimmedImg) : EndIf

StopProGUI()

Supported OS

Windows, Linux