sugar4.graphics.icon

Icons are small pictures that are used to decorate components. In Sugar, icons are SVG files that are re-coloured with a fill and a stroke colour. Typically, icons representing the system use a greyscale color palette, whereas icons representing people take on their selected XoColors.

This module provides modern icon widgets using native gesture handling and snapshot-based rendering for improved performance and accessibility.

Classes:

Icon: Basic icon widget for displaying themed icons EventIcon: Icon with mouse event handling using gesture controllers CanvasIcon: EventIcon with active/prelight states and styleable background CellRendererIcon: Icon renderer for use in tree/list views get_icon_file_name: Utility function to resolve icon paths get_surface: Utility function to get cairo surfaces for icons get_icon_state: Utility function to get state-based icon names

Attributes

SMALL_ICON_SIZE
STANDARD_ICON_SIZE
LARGE_ICON_SIZE

Classes

Icon	Basic Sugar icon widget.
EventIcon	Icon widget with mouse event handling using gesture controllers.
CanvasIcon	An EventIcon with active and prelight states, and a styleable background.
CellRendererIcon	Icon renderer for use in list/tree views.

Functions

get_icon_file_name(→ Optional[str])	Resolve icon name to file path using icon theme.
get_icon_state(→ Optional[str])	Get the closest icon name for a given state in percent.
get_surface(→ Optional[cairo.ImageSurface])	Get cairo surface for an icon with specified properties.

Module Contents

sugar4.graphics.icon.SMALL_ICON_SIZE = 16

sugar4.graphics.icon.STANDARD_ICON_SIZE = 48

sugar4.graphics.icon.LARGE_ICON_SIZE = 96

class sugar4.graphics.icon.Icon(icon_name: str | None = None, file_name: str | None = None, pixel_size: int = STANDARD_ICON_SIZE, **kwargs)

Bases: gi.repository.Gtk.Widget

Basic Sugar icon widget.

Displays themed icons with Sugar’s color customization features. Uses modern snapshot-based rendering for improved performance.

Properties:

icon_name (str): Icon name from theme file_name (str): Path to icon file pixel_size (int): Size in pixels fill_color (str): Fill color as hex string stroke_color (str): Stroke color as hex string xo_color (XoColor): Sugar color pair badge_name (str): Badge icon name alpha (float): Icon transparency (0.0-1.0) scale (float): Icon scale factor sensitive (bool): Whether icon appears sensitive

__gtype_name__ = 'SugarIcon'

do_snapshot(snapshot: gi.repository.Gtk.Snapshot)

Render icon using snapshot-based drawing.

do_measure(orientation: gi.repository.Gtk.Orientation, for_size: int) → Tuple[int, int, int, int]

Calculate widget size requirements.

get_icon_name() → str | None

set_icon_name(icon_name: str | None)

get_file_name() → str | None

set_file_name(file_name: str | None)

get_pixel_size() → int

set_pixel_size(size: int)

get_fill_color() → str | None

set_fill_color(color: str | None)

get_stroke_color() → str | None

set_stroke_color(color: str | None)

get_xo_color() → sugar4.graphics.xocolor.XoColor | None

set_xo_color(xo_color: sugar4.graphics.xocolor.XoColor | None)

get_badge_name() → str | None

set_badge_name(badge_name: str | None)

get_alpha() → float

set_alpha(alpha: float)

get_scale() → float

set_scale(scale: float)

get_badge_size() → int

Get size of badge icon in pixels.

icon_name

file_name

pixel_size

fill_color

stroke_color

xo_color

badge_name

alpha

scale

get_pixbuf() → gi.repository.GdkPixbuf.Pixbuf | None

Get pixbuf for this icon.

set_pixbuf(pixbuf: gi.repository.GdkPixbuf.Pixbuf | None)

Set pixbuf for this icon.

get_gtk_image() → gi.repository.Gtk.Image

Create a Gtk.Image from this icon for compatibility.

Returns:

Image widget with icon content

Return type:

Gtk.Image

class sugar4.graphics.icon.EventIcon(**kwargs)

Bases: Icon

Icon widget with mouse event handling using gesture controllers.

Provides click, press, and release events through modern gesture handling for better touch and accessibility support.

Signals:

clicked: Emitted when icon is clicked pressed: Emitted when icon is pressed released: Emitted when icon is released activate: Emitted when icon is activated

__gtype_name__ = 'SugarEventIcon'

__gsignals__

get_background_color() → gi.repository.Gdk.RGBA | None

Get background color.

set_background_color(color: gi.repository.Gdk.RGBA | None)

Set background color.

get_cache() → bool

Get cache setting.

set_cache(cache: bool)

Set cache setting.

background_color

cache

class sugar4.graphics.icon.CanvasIcon(**kwargs)

Bases: EventIcon

An EventIcon with active and prelight states, and a styleable background.

This icon responds to mouse hover and press states with visual feedback.

__gtype_name__ = 'SugarCanvasIcon'

do_snapshot(snapshot)

Override to render background based on state.

class sugar4.graphics.icon.CellRendererIcon

Icon renderer for use in list/tree views.

Modern implementations use different approaches for cell rendering. This provides compatibility for legacy code that may need adaptation.

Note: Consider using modern list/tree widget patterns instead.

set_icon_name(icon_name: str)

set_file_name(file_name: str)

set_xo_color(xo_color: sugar4.graphics.xocolor.XoColor)

set_fill_color(color: str)

set_stroke_color(color: str)

set_size(size: int)

get_surface(sensitive: bool = True) → cairo.ImageSurface | None

Get rendered surface.

sugar4.graphics.icon.get_icon_file_name(icon_name: str) → str | None

Resolve icon name to file path using icon theme.

Uses the system icon theme to find the appropriate icon file for the given icon name.

Parameters:

icon_name – Name of icon to resolve

Returns:

Path to icon file or None if not found

sugar4.graphics.icon.get_icon_state(base_name: str, perc: float, step: int = 5) → str | None

Get the closest icon name for a given state in percent.

Parameters:

• base_name – Base icon name (e.g., ‘network-wireless’)

• perc – Desired percentage between 0 and 100

• step – Step increment to find possible icons

Returns:

Icon name that represents given state, or None if not found

sugar4.graphics.icon.get_surface(icon_name: str | None = None, file_name: str | None = None, fill_color: str | None = None, stroke_color: str | None = None, pixel_size: int = STANDARD_ICON_SIZE, **kwargs) → cairo.ImageSurface | None

Get cairo surface for an icon with specified properties.

Parameters:

• icon_name – Icon name from theme

• file_name – Path to icon file

• fill_color – Fill color as hex string

• stroke_color – Stroke color as hex string

• pixel_size – Size in pixels

• **kwargs – Additional properties

Returns:

Cairo surface or None if icon not found