pyui.set_control_icon

Assigns an icon to a button-style control (create_button, create_ok_button, create_cancel_button, create_droplist_button) or to a static create_image control. On buttons the icon is displayed to the left of the button text, or centered if the button has no text; an image control shows nothing but the icon. The icon is automatically scaled to match the current display scaling (DPI) of the dialog.

pyui.set_control_icon(control, icon_files [, options])
control:set_control_icon(icon_files, options)

Parameters

	Type	Description
control	control_handle	Control handle of a button-style or image control
icon_files	path_handle or {path_handle, ...}	A single icon file, or a list of files with the same motif at different resolutions (see notes)
options	table	Optional options table, see below

Recognized fields of the options table:

	Type	Description
size	integer	Icon size in pixels at 100 % display scaling (default 16). The effective pixel size grows with the display scaling, e.g. 16 becomes 24 physical pixels at 150 %.

Return value

None

Note

Two ways to provide the icon, both supporting crisp display at any display scaling:

1. A single .ico file containing the icon at multiple resolutions (16, 24, 32 and 48 pixels are recommended). Windows selects the best-matching embedded resolution and scales it as needed.
2. A list of raster images (.png recommended; .bmp, .jpg and .tif also work) with the same motif at different resolutions, e.g. 16, 32 and 48 pixels. The smallest image that still covers the required size is selected and downscaled if needed (downscaling looks considerably better than upscaling, so provide generous resolutions). PNG transparency is respected; non-square images are centered on a transparent background.

A single raster image also works, at the cost of blurring when its resolution does not match.

Call this function directly after creating the button, before the dialog is laid out: the measured button size includes the icon. If the icon is assigned to a button of an already visible dialog, call update_dialog_layout afterwards.

To make a button taller (e.g. a prominent action button of two or three lines of height with a larger icon), combine this function with set_control_min_height, which takes dialog units (8 DLU correspond to roughly one line of text):

Example:

function open_dialog()
    local dialog = pyui.create_dialog("my_plugin_dialog")
    dialog:set_window_title("Icon buttons")

    -- variant 1: multi-resolution .ico file
    local export_button = dialog:create_button(1, "Export")
    export_button:set_control_icon(pyio.get_plugin_folder_path("icons/export.ico"))

    -- variant 2: png set, two lines tall with a larger icon
    local run_button = dialog:create_button(1, "Run machining")
    run_button:set_control_icon({
        pyio.get_plugin_folder_path("icons/run_16.png"),
        pyio.get_plugin_folder_path("icons/run_32.png"),
        pyio.get_plugin_folder_path("icons/run_48.png"),
    }, {size = 32})
    run_button:set_control_min_height(16)

    dialog:create_ok_button(1)
    pyui.run_modal_dialog(dialog)
end

Version Support:

Minimum PYTHA Version: V27

The function is absent (nil) in older versions, so a plugin can probe for it with if pyui.set_control_icon then ... end.

See also

Control Gallery, create_button, create_droplist_button, set_control_text, update_dialog_layout, get_plugin_folder_path