sugar4.graphics

Visual components, styling, and UI widgets for Sugar activities.

Attributes

`SMALL_ICON_SIZE`
`STANDARD_ICON_SIZE`
`LARGE_ICON_SIZE`

Classes

`XoColor`	Defines color for XO
`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_surface`(→ Optional[cairo.ImageSurface])	Get cairo surface for an icon with specified properties.
`get_icon_state`(→ Optional[str])	Get the closest icon name for a given state in percent.

Package Contents

class sugar4.graphics.XoColor(color_string=None)[source]

Defines color for XO

This class represents a pair of colors (stroke and fill) that can be used throughout Sugar activities. Colors can be parsed from strings, loaded from user settings, or chosen randomly.

Parameters:: color_string (str, optional) – Color specification in one of these formats: - “stroke_hex,fill_hex” (e.g., “#FF0000,#00FF00”) - “white” for white theme - “insensitive” for disabled/grayed theme - None to use user’s color from settings or random if not available

Examples

>>> #from string
>>> color = XoColor("#FF0000,#00FF00")
>>> print(color.get_stroke_color())  # "#FF0000"
>>> print(color.get_fill_color())    # "#00FF00"

>>> # create user's color (or random if not set)
>>> color = XoColor()

>>> # themed colors
>>> white_color = XoColor("white")
>>> disabled_color = XoColor("insensitive")

__eq__(other)[source]

Check if two XoColor objects are equal.

Parameters:: other (object) – Another XoColor object to compare
Returns:: True if both stroke and fill colors match
Return type:: bool

__ne__(other)[source]: Check if two XoColor objects are not equal.

__hash__()[source]: Make XoColor hashable for use in sets and as dict keys.

__str__()[source]: String representation of XoColor.

__repr__()[source]: Detailed string representation of XoColor.

get_stroke_color()[source]

Returns:: stroke color in HTML hex format (#RRGGBB)
Return type:: str

get_fill_color()[source]

Returns:: fill color in HTML hex format (#RRGGBB)
Return type:: str

to_string()[source]

Returns:: formatted string in the format “#STROKEHEX,#FILLHEX”
Return type:: str

classmethod from_string(color_string)[source]

Create XoColor from string representation.

Parameters:: color_string (str) – Color string to parse
Returns:: New XoColor instance
Return type:: XoColor
Raises:: ValueError – If color_string cannot be parsed

classmethod get_random_color()[source]

Get a random XO color.

Returns:: Random XoColor instance from the standard palette
Return type:: XoColor

to_rgba_tuple(alpha=1.0)[source]

Convert colors to RGBA tuples for use with Cairo and modern graphics.

Parameters:: alpha (float) – Alpha value (0.0 - 1.0)
Returns:: ((r, g, b, a), (r, g, b, a)) for stroke and fill colors
Return type:: tuple

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

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)[source]: Render icon using snapshot-based drawing.

do_measure(orientation: gi.repository.Gtk.Orientation, for_size: int) → Tuple[int, int, int, int][source]: Calculate widget size requirements.

get_icon_name() → str | None[source]

set_icon_name(icon_name: str | None)[source]

get_file_name() → str | None[source]

set_file_name(file_name: str | None)[source]

get_pixel_size() → int[source]

set_pixel_size(size: int)[source]

get_fill_color() → str | None[source]

set_fill_color(color: str | None)[source]

get_stroke_color() → str | None[source]

set_stroke_color(color: str | None)[source]

get_xo_color() → sugar4.graphics.xocolor.XoColor | None[source]

set_xo_color(xo_color: sugar4.graphics.xocolor.XoColor | None)[source]

get_badge_name() → str | None[source]

set_badge_name(badge_name: str | None)[source]

get_alpha() → float[source]

set_alpha(alpha: float)[source]

get_scale() → float[source]

set_scale(scale: float)[source]

get_badge_size() → int[source]: 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[source]: Get pixbuf for this icon.

set_pixbuf(pixbuf: gi.repository.GdkPixbuf.Pixbuf | None)[source]: Set pixbuf for this icon.

get_gtk_image() → gi.repository.Gtk.Image[source]

Create a Gtk.Image from this icon for compatibility.

Returns:: Image widget with icon content
Return type:: Gtk.Image

class sugar4.graphics.EventIcon(**kwargs)[source]

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[source]: Get background color.

set_background_color(color: gi.repository.Gdk.RGBA | None)[source]: Set background color.

get_cache() → bool[source]: Get cache setting.

set_cache(cache: bool)[source]: Set cache setting.

background_color

cache

class sugar4.graphics.CanvasIcon(**kwargs)[source]

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)[source]: Override to render background based on state.

class sugar4.graphics.CellRendererIcon[source]

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)[source]

set_file_name(file_name: str)[source]

set_xo_color(xo_color: sugar4.graphics.xocolor.XoColor)[source]

set_fill_color(color: str)[source]

set_stroke_color(color: str)[source]

set_size(size: int)[source]

get_surface(sensitive: bool = True) → cairo.ImageSurface | None[source]: Get rendered surface.

sugar4.graphics.get_icon_file_name(icon_name: str) → str | None[source]

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

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

sugar4.graphics.get_icon_state(base_name: str, perc: float, step: int = 5) → str | None[source]

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