sugar4.graphics package

Submodules

sugar4.graphics.alert module

Alerts appear in an activity below the toolbox and above the canvas.

Alert and the derived TimeoutAlert, ConfirmationAlert, ErrorAlert, and NotifyAlert, each have a title, a message and optional buttons.

Alert will emit a response signal when a button is clicked.

The TimeoutAlert and NotifyAlert display a countdown and will emit a response signal when a timeout occurs.

Example

Create a simple alert message.

from sugar4.graphics.alert import Alert

# Create a new simple alert
alert = Alert()

# Set the title and text body of the alert
alert.props.title = _('Title of Alert Goes Here')
alert.props.msg = _('Text message of alert goes here')

# Add the alert to the activity
self.add_alert(alert)
alert.show()

STABLE.

class sugar4.graphics.alert.Alert(*args: Any, **kwargs: Any)

Bases: Box

Alerts are inside the activity window instead of being a separate popup window. They do not hide the canvas.

Use add_alert() and remove_alert() to add and remove an alert. These methods are inherited by an Activity via superclass Window.

The alert is placed between the canvas and the toolbox, or above the canvas in fullscreen mode.

Parameters:

• title (str) – the title of the alert

• message (str) – the message of the alert

• icon (str) – the icon that appears at the far left

__init__(**kwargs)

do_set_property(pspec, value)

Set alert property, GObject internal method. Use the alert.props object, eg:

alert.props.title = 'Are you happy?'

do_get_property(pspec)

Get alert property, GObject internal method. Use the alert.props object, eg:

title = alert.props.title

add_entry()

Create an entry and add it to the alert.

The entry is placed after the title and before the buttons.

Caller is responsible for capturing the entry text in the response signal handler or a Gtk.Entry signal handler.

Returns:

the entry added to the alert

Return type:

Gtk.Entry

add_button(response_id, label, icon=None, position=-1)

Create a button and add it to the alert.

The button is added to the end of the alert.

When the button is clicked, the response signal will be emitted, along with a response identifier.

Parameters:

• response_id (int) – the response identifier, a Gtk.ResponseType constant or any positive integer,

• label (str) – a label for the button

• icon (Icon or Gtk.Image, optional) – an icon for the button

• position (int, optional) – the position of the button in the box of buttons,

Returns:

the button added to the alert

Return type:

Gtk.Button

remove_button(response_id)

Remove a button from the alert.

The button is selected for removal using the response identifier that was passed to add_button().

Parameters:

response_id (int) – the response identifier

Returns:

None

class sugar4.graphics.alert.ConfirmationAlert(*args: Any, **kwargs: Any)

Bases: Alert

An alert with two buttons; Ok and Cancel.

When a button is clicked, the ConfirmationAlert will emit a response signal with a response identifier. For the Ok button, the response identifier will be Gtk.ResponseType.OK. For the Cancel button, Gtk.ResponseType.CANCEL.

Parameters:

**kwargs – parameters for Alert

__init__(**kwargs)

class sugar4.graphics.alert.ErrorAlert(*args: Any, **kwargs: Any)

Bases: Alert

An alert with one button; Ok.

When the button is clicked, the ErrorAlert will emit a response signal with a response identifier Gtk.ResponseType.OK.

Parameters:

**kwargs – parameters for Alert

__init__(**kwargs)

class sugar4.graphics.alert.TimeoutAlert(*args: Any, **kwargs: Any)

Bases: _TimeoutAlert

A timed alert with two buttons; Continue and Cancel. The Continue button contains a countdown of seconds remaining.

When a button is clicked, the TimeoutAlert will emit a response signal with a response identifier. For the Continue button, the response identifier will be Gtk.ResponseType.OK. For the Cancel button, Gtk.ResponseType.CANCEL.

If the countdown reaches zero before a button is clicked, the TimeoutAlert will emit a response signal with a response identifier of -1.

Parameters:

• timeout (int, optional) – time in seconds, default 5

• **kwargs – parameters for Alert

__init__(timeout=5, **kwargs)

class sugar4.graphics.alert.NotifyAlert(*args: Any, **kwargs: Any)

Bases: _TimeoutAlert

A timed alert with one button; Ok. The button contains a countdown of seconds remaining.

When the button is clicked, the NotifyAlert will emit a response signal with a response identifier Gtk.ResponseType.OK.

If the countdown reaches zero before the button is clicked, the NotifyAlert will emit a response signal with a response identifier of -1.

Parameters:

• timeout (int, optional) – time in seconds, default 5

• **kwargs – parameters for Alert

__init__(timeout=5, **kwargs)

sugar4.graphics.animator module

Animator

The animator module provides a simple framework to create animations.

Example

Animate the size of a window:

from gi.repository import Gtk
from sugar4.graphics.animator import Animator, Animation

# Construct a window to animate
w = Gtk.Window()
w.connect('destroy', lambda w: app.quit())

# Start the animation when the window is shown
w.connect('realize', lambda self: animator.start())
w.present()

# Construct a 5 second animator
animator = Animator(5, widget=w)

# Create an animation subclass to animate the widget
class SizeAnimation(Animation):
    def __init__(self):
        # Tell the animation to give us values between 20 and
        # 420 during the animation
        Animation.__init__(self, 20, 420)

    def next_frame(self, frame):
        size = int(frame)
        w.set_default_size(size, size)

# Add the animation to the animator
animation = SizeAnimation()
animator.add(animation)

# The animation runs inside a GLib main loop
app.run()

STABLE.

class sugar4.graphics.animator.Animator(*args: Any, **kwargs: Any)

Bases: GObject

The animator class manages the timing for calling the animations.

The animations can be added using the add function and then started with the start function. If multiple animations are added, then they will be played back at the same time and rate as each other.

The completed signal is emitted upon the completion of the animation and also when the stop function is called.

Parameters:

• duration (float) – the duration of the animation in seconds

• fps (int, optional) – the number of animation callbacks to make per second (frames per second). This is used as fallback when frame clock is not available.

• easing (int) – the desired easing mode, either EASE_OUT_EXPO or EASE_IN_EXPO

• widget (Gtk.Widget) – one of the widgets that the animation is acting on. If supplied, the animation will run on the frame clock of the widget for smoother animation.

Note

When creating an animation, take into account the limited cpu power on some devices, such as the XO. Setting the fps too high can use significant cpu usage.

__init__(duration, fps=20, easing=0, widget=None)

add(animation)

Add an animation to this animator.

Parameters:

animation (sugar4.graphics.animator.Animation) – the animation instance to add

remove_all()

Remove all animations and stop this animator.

start()

Start the animation running. This will stop and restart the animation if the animation is currently running.

stop()

Stop the animation and emit the completed signal.

class sugar4.graphics.animator.Animation(start, end)

Bases: object

The animation class is a base class for creating an animation. It should be subclassed. Subclasses should specify a next_frame function to set the required properties based on the animation progress. The range of the frame value passed to the next_frame function is defined by the start and end values.

Parameters:

• start (float) – the first frame value for the next_frame method

• end (float) – the last frame value for the next_frame method

# Create an animation subclass
class MyAnimation(Animation):
    def __init__(self, thing):
        # Tell the animation to give us values between 0.0 and
        # 1.0 during the animation
        Animation.__init__(self, 0.0, 1.0)
        self._thing = thing

    def next_frame(self, frame):
        # Use the `frame` value to set properties
        self._thing.set_green_value(frame)

__init__(start, end)

do_frame(t, duration, easing)

This method is called by the animator class every frame. This method calculates the frame value to then call next_frame.

Parameters:

• t (float) – the current time elapsed of the animation in seconds

• duration (float) – the length of the animation in seconds

• easing (int) – the easing mode passed to the animator

next_frame(frame)

This method is called every frame and should be overridden by subclasses.

Parameters:

frame (float) – a value between start and end representing the current progress in the animation

do_stop()

This method is called whenever the animation is stopped, either due to the animation ending or being stopped by the animation. next_frame will not be called after do_stop, unless the animation is restarted.

Added in version 0.109.0.3.

This should be used in subclasses if they bind any signals. Eg. if they bind the draw signal for a widget:

class SignalAnimation(Animation):

    def __init__(self, widget):
        Animation.__init__(self, 0, 1)
        self._draw_hid = None
        self._widget = widget

    def next_frame(self, frame):
        self._frame = frame
        if self._draw_hid is None:
            self._draw_hid = self._widget.connect_after(
                'draw', self.__draw_cb)
        self._widget.queue_draw()

    def __draw_cb(self, widget, cr):
        cr.save()
        # Do the draw
        cr.restore()

    def do_stop(self):
        self._widget.disconnect(self._draw_hid)
        self._widget.queue_draw()

class sugar4.graphics.animator.FadeAnimation(widget, start_opacity=0.0, end_opacity=1.0)

Bases: Animation

A convenience animation class for fading widgets in/out.

Parameters:

• widget (Gtk.Widget) – The widget to animate

• start_opacity (float) – Starting opacity (0.0 to 1.0)

• end_opacity (float) – Ending opacity (0.0 to 1.0)

__init__(widget, start_opacity=0.0, end_opacity=1.0)

next_frame(frame)

Update widget opacity.

class sugar4.graphics.animator.ScaleAnimation(widget, start_scale=0.0, end_scale=1.0)

Bases: Animation

A convenience animation class for scaling widgets.

Parameters:

• widget (Gtk.Widget) – The widget to animate

• start_scale (float) – Starting scale factor

• end_scale (float) – Ending scale factor

__init__(widget, start_scale=0.0, end_scale=1.0)

next_frame(frame)

Update widget scale.

class sugar4.graphics.animator.MoveAnimation(widget, start_pos, end_pos)

Bases: Animation

A convenience animation class for moving widgets.

Parameters:

• widget (Gtk.Widget) – The widget to animate

• start_pos (tuple) – Starting position (x, y)

• end_pos (tuple) – Ending position (x, y)

__init__(widget, start_pos, end_pos)

next_frame(frame)

Update widget position.

class sugar4.graphics.animator.ColorAnimation(start_color, end_color, callback)

Bases: Animation

A convenience animation class for animating colors.

Parameters:

• start_color (tuple) – Starting RGBA color (r, g, b, a)

• end_color (tuple) – Ending RGBA color (r, g, b, a)

• callback (function) – Function to call with interpolated color

__init__(start_color, end_color, callback)

next_frame(frame)

Interpolate color and call callback.

sugar4.graphics.icon module

Icons

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

class sugar4.graphics.icon.Icon(*args: Any, **kwargs: Any)

Bases: 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

__init__(icon_name: str | None = None, file_name: str | None = None, pixel_size: int = 48, **kwargs)

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() → XoColor | None

set_xo_color(xo_color: 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.

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(*args: Any, **kwargs: Any)

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

__init__(**kwargs)

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.

class sugar4.graphics.icon.CanvasIcon(*args: Any, **kwargs: Any)

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.

__init__(**kwargs)

do_snapshot(snapshot)

Override to render background based on state.

class sugar4.graphics.icon.CellRendererIcon

Bases: object

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.

__init__()

set_icon_name(icon_name: str)

set_file_name(file_name: str)

set_xo_color(xo_color: 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 = 48, **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

sugar4.graphics.menuitem module

MenuItem

Sugar-style menu items with icon and accelerator support. This implementation replaces deprecated ImageMenuItem with modern equivalents.

class sugar4.graphics.menuitem.MenuItem(*args: Any, **kwargs: Any)

Bases: Button

A Sugar-style menu item with icon and text support.

This replaces the deprecated ImageMenuItem with a Button that can be used in menus and popover menus.

Parameters:

• text_label (str) – Text to display on the menu item

• icon_name (str) – Name of icon to display

• text_maxlen (int) – Maximum text length before ellipsizing

• xo_color – XO color scheme for the icon

• file_name (str) – Path to icon file

__init__(text_label: str | None = None, icon_name: str | None = None, text_maxlen: int = 60, xo_color=None, file_name: str | None = None)

set_accelerator(accelerator: str | None)

Set keyboard accelerator for this menu item.

Parameters:

accelerator (str) – Accelerator string (e.g., ‘<Ctrl>s’)

get_accelerator() → str | None

Get the current accelerator string.

Returns:

Current accelerator or None

Return type:

str

set_text(text: str)

Set the text label of the menu item.

Parameters:

text (str) – New text to display

get_text() → str

Get the current text of the menu item.

Returns:

Current text or empty string

Return type:

str

class sugar4.graphics.menuitem.MenuSeparator(*args: Any, **kwargs: Any)

Bases: Separator

A separator for use in menus.

Simple wrapper around Gtk.Separator with menu-appropriate styling.

__init__()

sugar4.graphics.objectchooser module

STABLE.

sugar4.graphics.objectchooser.get_preview_pixbuf(preview_data, width=-1, height=-1)

Retrieve a pixbuf with the content of the preview field

Parameters:

preview_data (bytes) – preview data from the metadata dictionary. Can’t be None. Returned from the sugar4.datastore.datastore.DSObject.get_metadata() method.

Keyword Arguments:

• width (int) – the pixbuf width, if is not set,

• used (the default height will be)

• height (int) – the pixbuf height, if is not set,

• used

Returns:

the generated Pixbuf None: if it could not be created

Return type:

GdkPixbuf.Pixbuf

Example

pixbuf = get_preview_pixbuf(metadata.get(‘preview’, ‘’)) has_preview = pixbuf is not None

if has_preview:

im = Gtk.Image() im.set_from_pixbuf(pixbuf) box.append(im) im.show()

class sugar4.graphics.objectchooser.ObjectChooser(parent=None, what_filter=None, filter_type=None, show_preview=False)

Bases: object

UI interface for object choosers.

Object choosers can be used by activities to allow the user to select objects from the file system or from some other similar source.

Keyword Arguments:

• parent (Gtk.Widget) – the widget calling ObjectChooser

• what_filter (str) – an activity bundle_id or a generic mime type as defined in sugar4.mime used to determine which objects will be presented in the object chooser

• filter_type (str) –

  should be one of [None, FILTER_TYPE_GENERIC_MIME, FILTER_TYPE_ACTIVITY, FILTER_TYPE_MIME_BY_ACTIVITY]

  If filter_type is None, the default behavior of the what_filter is applied (for backward compatibility), this option is DEPRECATED.

  If filter_type is FILTER_TYPE_GENERIC_MIME, the what_filter should be a generic mime type defined in mime.py; the object chooser will filter based in the ‘mime_type’ metadata field.

  If filter_type is FILTER_TYPE_ACTIVITY, the what_filter should by an activity bundle_id; the object chooser will filter based in the ‘activity’ metadata field.

  If filter_type is FILTER_TYPE_MIME_BY_ACTIVITY, the what_filter should be an activity bundle_id; the object chooser will filter based on the ‘mime_type’ metadata field and the mime types defined by the activity in the activity.info file.

• show_preview (bool) – if True will show the preview image associated with the object in the Journal. This option is only available if filter_type is selected.

Examples

chooser = ObjectChooser(self._activity, what_filter=’Image’)

chooser = ObjectChooser(parent=self,

what_filter=self.get_bundle_id(), filter_type=FILTER_TYPE_ACTIVITY)

__init__(parent=None, what_filter=None, filter_type=None, show_preview=False)

run()

Runs the object chooser and displays it.

Returns:

Gtk.ResponseType constant, the response received from displaying the object chooser.

get_selected_object()

Gets the object selected using the object chooser.

Returns:

the object selected

Return type:

object

destroy()

Destroys and cleans up (disposes) the object chooser.

sugar4.graphics.palette module

class sugar4.graphics.palette.Palette(*args: Any, **kwargs: Any)

Bases: PaletteWindow

Floating palette implementation.

This class dynamically switches between one of two encapsulated child widget types: a _PaletteWindowWidget or a _PaletteMenuWidget.

The window widget, created by default, acts as the container for any type of widget the user may wish to add. It can optionally display primary text, secondary text, and an icon at the top of the palette.

If the user attempts to access the ‘menu’ property, the window widget is destroyed and the palette is dynamically switched to use a menu widget. This maintains the same look and feel as a normal palette, allowing submenus and so on.

__init__(label=None, accel_path=None, text_maxlen=60, **kwargs)

get_full_size_request()

Get the full size request for the palette.

popup(immediate=False)

Show the palette.

popdown(immediate=False, state=None)

Hide the palette.

Parameters:

• immediate (bool) – if True, hide instantly. If False, use animation.

• state – deprecated parameter, ignored.

on_enter()

set_primary_text(label, accel_path=None)

get_primary_text()

set_secondary_text(label)

get_secondary_text()

set_icon(icon)

get_icon()

set_icon_visible(visible)

get_icon_visible()

set_content(widget)

Set the main content widget for the palette window.

get_label_width()

get_menu()

class sugar4.graphics.palette.PaletteActionBar(*args: Any, **kwargs: Any)

Bases: Box

__init__()

add_action(label, icon_name=None)

sugar4.graphics.palettegroup module

sugar4.graphics.palettegroup.get_group(group_id)

sugar4.graphics.palettegroup.popdown_all()

class sugar4.graphics.palettegroup.Group(*args: Any, **kwargs: Any)

Bases: GObject

__init__()

is_up()

get_state()

add(palette)

remove(palette)

popdown()

sugar4.graphics.palettemenu module

PaletteMenu

The palettemenu module is the main port of call for making palettes. It covers creating menu items, separators and placing them in a box.

This implementation modernizes the palette menu system while maintaining compatibility with Sugar’s palette interface patterns.

Example

Create a palette menu with 2 items with a separator in the middle.

from gi.repository import Gtk
from gettext import gettext as _

from sugar4.graphics.palette import Palette
from sugar4.graphics.palettemenu import PaletteMenuBox
from sugar4.graphics.palettemenu import PaletteMenuItem
from sugar4.graphics.palettemenu import PaletteMenuItemSeparator


class ItemPalette(Palette):
    def __init__(self):
        Palette.__init__(
            self, primary_text='List Item')
        box = PaletteMenuBox()
        self.set_content(box)

        menu_item = PaletteMenuItem(
            _('Edit'), icon_name='toolbar-edit')
        menu_item.connect('activate', self.__edit_cb)
        box.append_item(menu_item)

        sep = PaletteMenuItemSeparator()
        box.append_item(sep)

        menu_item = PaletteMenuItem(
            _('Delete'), icon_name='edit-delete')
        box.append_item(menu_item)

    def __edit_cb(self, menu_item):
        print('Edit...')

# Usually the Palette instance is returned in a create_palette function
p = ItemPalette()
p.popup()

Add a palettebox to a toolbutton:

image = ToolButton('insert-picture')
image.set_tooltip(_('Insert Image'))
toolbar_box.toolbar.insert(image, -1)

palette = image.get_palette()
box = PaletteMenuBox()
palette.set_content(box)

menu_item = PaletteMenuItem(_('Floating'))
menu_item.connect('activate', self.__image_cb, True)
box.append_item(menu_item)

class sugar4.graphics.palettemenu.PaletteMenuBox(*args: Any, **kwargs: Any)

Bases: Box

The PaletteMenuBox is a box that is useful for making palettes.

It supports adding sugar4.graphics.palettemenu.PaletteMenuItem, sugar4.graphics.palettemenu.PaletteMenuItemSeparator and it automatically adds padding to other widgets.

__init__()

append_item(item_or_widget, horizontal_padding=None, vertical_padding=None)

Add a menu item, separator or other widget to the end of the palette (similar to Gtk.Box.append).

If an item is appended (a sugar4.graphics.palettemenu.PaletteMenuItem or a sugar4.graphics.palettemenu.PaletteMenuItemSeparator) no padding will be added, as that is handled by the item. If a widget is appended (Gtk.Widget subclass) padding will be added.

Parameters:

• item_or_widget (Gtk.Widget or menu item or separator) – item or widget to add to the palette

• horizontal_padding (int) – by default, sugar4.graphics.style.DEFAULT_SPACING is applied

• vertical_padding (int) – by default, sugar4.graphics.style.DEFAULT_SPACING is applied

Returns:

None

class sugar4.graphics.palettemenu.PaletteMenuItemSeparator(*args: Any, **kwargs: Any)

Bases: Separator

Horizontal separator to put in a palette.

__init__()

class sugar4.graphics.palettemenu.PaletteMenuItem(*args: Any, **kwargs: Any)

Bases: Button

A palette menu item is a line of text, and optionally an icon, that the user can activate.

The activate signal is usually emitted when the item is clicked. It has no arguments. When a menu item is activated, the palette is also closed.

This implementation replaces EventBox with Button for better accessibility and modern interaction patterns.

Parameters:

• text_label (str) – a text to display in the menu

• icon_name (str) – the name of a sugar icon to be displayed. Takes precedence over file_name

• text_maxlen (int) – the desired maximum width of the label, in characters. By default set to 60 chars

• xo_color (sugar4.graphics.XoColor) – the color to be applied to the icon

• file_name (str) – the path to a svg file used as icon

• accelerator (str) – a text used to display the keyboard shortcut associated to the menu

__init__(text_label=None, icon_name=None, text_maxlen=60, xo_color=None, file_name=None, accelerator=None)

set_label(text_label)

Set the text label of the menu item.

Parameters:

text_label (str) – New text to display

get_label()

Get the current text of the menu item.

Returns:

Current text or empty string

Return type:

str

set_image(icon)

Set the icon of the menu item.

Parameters:

icon (Icon) – Icon widget to display

set_accelerator(text)

Set the accelerator text for the menu item.

Parameters:

text (str) – Accelerator text to display (e.g., “Ctrl+S”)

set_sensitive(sensitive)

Set the sensitivity of the menu item.

Parameters:

sensitive (bool) – Whether the item should be sensitive

sugar4.graphics.palettemenu.create_menu_item(text, icon_name=None, callback=None, accelerator=None)

Create a basic menu item with common parameters.

Parameters:

• text (str) – Menu item text

• icon_name (str) – Optional icon name

• callback (function) – Optional callback function

• accelerator (str) – Optional accelerator text

Returns:

The created menu item

Return type:

PaletteMenuItem

sugar4.graphics.palettemenu.create_separator()

Create a menu separator.

Returns:

The created separator

Return type:

PaletteMenuItemSeparator

sugar4.graphics.palettemenu.create_submenu_item(text, submenu_items, icon_name=None)

Create a menu item that expands to show submenu items.

Parameters:

• text (str) – Menu item text

• submenu_items (list) – List of submenu items

• icon_name (str) – Optional icon name

Returns:

The created submenu item

Return type:

PaletteMenuItem

class sugar4.graphics.palettemenu.PaletteMenuGroup(name=None)

Bases: object

A group of related menu items that can be managed together.

__init__(name=None)

add_item(item)

Add an item to this group.

set_sensitive(sensitive)

Set sensitivity of all items in the group.

set_visible(visible)

Set visibility of all items in the group.

class sugar4.graphics.palettemenu.PaletteMenuBuilder

Bases: object

Builder class for creating complex palette menus.

__init__()

add_item(text, icon_name=None, callback=None, accelerator=None, group=None)

Add a menu item to the builder.

add_separator()

Add a separator to the builder.

get_menu_box()

Get the constructed menu box.

get_group(name)

Get a menu group by name.

sugar4.graphics.palettewindow module

class sugar4.graphics.palettewindow.MouseSpeedDetector(*args: Any, **kwargs: Any)

Bases: GObject

Detects mouse movement speed for palette activation.

__init__(delay, thresh)

Create MouseSpeedDetector object.

Parameters:

• delay – delay in msec

• thresh – threshold in pixels (per tick of ‘delay’ msec)

start()

Start detecting mouse speed.

stop()

Stop detecting mouse speed.

class sugar4.graphics.palettewindow.PaletteWindow(*args: Any, **kwargs: Any)

Bases: GObject

Base class for palette windows.

__init__(**kwargs)

destroy()

set_invoker(invoker)

get_invoker()

set_content(widget)

Set the main content widget for the palette window.

is_up()

set_group_id(group_id)

get_group_id()

Get the current group ID.

update_position()

Update the position of the palette.

get_full_size_request()

Get the full size request for the palette.

popup(immediate=False)

Show the palette.

popdown(immediate=False)

Hide the palette.

on_invoker_enter()

on_invoker_leave()

on_enter()

on_leave()

get_rect()

class sugar4.graphics.palettewindow.Invoker(*args: Any, **kwargs: Any)

Bases: GObject

Base class for palette invokers.

ANCHORED = 0

AT_CURSOR = 1

BOTTOM = [(0.0, 0.0, 0.0, 1.0), (-1.0, 0.0, 1.0, 1.0)]

RIGHT = [(0.0, 0.0, 1.0, 0.0), (0.0, -1.0, 1.0, 1.0)]

TOP = [(0.0, -1.0, 0.0, 0.0), (-1.0, -1.0, 1.0, 0.0)]

LEFT = [(-1.0, 0.0, 0.0, 0.0), (-1.0, -1.0, 0.0, 1.0)]

__init__()

attach(parent)

detach()

get_position_for_alignment(alignment, palette_dim)

Get position for specific alignment if it fits on screen.

get_position(palette_dim)

get_alignment(palette_dim)

has_rectangle_gap()

draw_rectangle(event, palette)

notify_popup()

notify_popdown()

notify_mouse_enter()

notify_mouse_leave()

notify_right_click(x=None, y=None)

Notify the palette invoker of a right click and expand the palette as required. The x and y args should be that of where the event happened, relative to the root of the screen.

Args

x (float): the x coord of the event relative to the root

of the screen, eg. Gdk.EventTouch.x_root

y (float): the y coord of the event relative to the root

of the screen, eg. Gdk.EventTouch.y_root

notify_toggle_state()

get_palette()

set_palette(palette)

get_cache_palette()

set_cache_palette(cache_palette)

get_toggle_palette()

set_toggle_palette(toggle_palette)

get_lock_palette()

set_lock_palette(lock_palette)

primary_text_clicked()

get_rect()

Get the rectangle for this invoker - implemented by subclasses.

get_toplevel()

Get the toplevel window - implemented by subclasses.

class sugar4.graphics.palettewindow.WidgetInvoker(*args: Any, **kwargs: Any)

Bases: Invoker

Invoker for general widgets.

__init__(parent=None, widget=None)

attach_widget(parent, widget=None)

detach()

get_rect()

Get the rectangle for this invoker - implemented by subclasses.

has_rectangle_gap()

draw_rectangle(cr, palette)

get_widget()

set_widget(widget)

get_toplevel()

Get the toplevel window - implemented by subclasses.

notify_popup()

notify_popdown()

class sugar4.graphics.palettewindow.CursorInvoker(*args: Any, **kwargs: Any)

Bases: Invoker

Invoker that tracks cursor position.

__init__(parent=None)

attach(parent)

detach()

Detach from the parent.

get_rect()

Get the rectangle for this invoker - implemented by subclasses.

get_toplevel()

Get the toplevel window - implemented by subclasses.

class sugar4.graphics.palettewindow.ToolInvoker(*args: Any, **kwargs: Any)

Bases: WidgetInvoker

A palette invoker for toolbar buttons and other items. this invoker will properly align the palette so that is perpendicular to the toolbar (a horizontal toolbar will spawn a palette going downwards). it also draws the highlights specific to a toolitem.

for sugar4.graphics.toolbutton.toolbutton and subclasses, you should not use the toolinvoker directly. instead, just subclass the tool button and override the create_palette function.

Parameters:

parent (gtk.widget) – toolitem to connect invoker to

__init__(parent=None)

attach_tool(widget)

Attach a toolitem to the invoker. Same behaviour as passing the parent argument to the constructor.

Parameters:

widget (Gtk.Widget) – toolitem to connect invoker to

primary_text_clicked()

notify_popup()

notify_popdown()

class sugar4.graphics.palettewindow.TreeViewInvoker(*args: Any, **kwargs: Any)

Bases: Invoker

Invoker for TreeView cells.

__init__()

attach_treeview(tree_view)

detach()

get_rect()

Get the rectangle for this invoker - implemented by subclasses.

get_toplevel()

Get the toplevel window - implemented by subclasses.

notify_popdown()

sugar4.graphics.radiopalette module

RadioPalette

Radio palette provides a way to create radio button groups within palettes, allowing users to select one option from multiple choices.

This implementation modernizes the radio palette system while maintaining compatibility with Sugar’s palette interface patterns.

Example

Create a radio palette with multiple tool options.

from gi.repository import Gtk
from sugar4.graphics.radiopalette import RadioToolsButton, RadioPalette
from sugar4.graphics.toolbutton import ToolButton

# Create the main radio button
radio_button = RadioToolsButton(
    icon_name='tool-brush',
    tooltip='Drawing Tools'
)

# Create the palette
palette = RadioPalette(primary_text='Drawing Tools')
radio_button.set_palette(palette)

# Add tool options
brush_btn = ToolButton(icon_name='tool-brush')
palette.append(brush_btn, 'Brush')

pen_btn = ToolButton(icon_name='tool-pen')
palette.append(pen_btn, 'Pen')

class sugar4.graphics.radiopalette.RadioMenuButton(*args: Any, **kwargs: Any)

Bases: ToolButton

A toolbar button that shows a radio palette when clicked.

__init__(**kwargs)

get_selected_button()

set_selected_button(button)

class sugar4.graphics.radiopalette.RadioToolsButton(*args: Any, **kwargs: Any)

Bases: RadioMenuButton

__init__(**kwargs)

do_clicked()

class sugar4.graphics.radiopalette.RadioPalette(*args: Any, **kwargs: Any)

Bases: Palette

A palette containing radio button options.

__init__(**kwargs)

append(button, label)

Add a button option to the radio palette.

Parameters:

• button – The ToolButton to add to the radio group

• label – The label text for this option

update_button()

popdown(immediate=True)

Hide the palette.

Parameters:

• immediate (bool) – if True, hide instantly. If False, use animation.

• state – deprecated parameter, ignored.

popup(immediate=True)

Show the palette.

get_buttons()

get_selected_button()

sugar4.graphics.radiotoolbutton module

RadioToolButton

Provides a RadioToolButton class, similar to a “push” button. A group of RadioToolButtons can be set, so that only one can be selected at a time. When a button is clicked, it depresses and is shaded darker.

It is also possible to set a tooltip to be dispalyed when the user scrolls over it with their cursor as well as an accelerator keyboard shortcut.

class sugar4.graphics.radiotoolbutton.RadioToolButton(*args: Any, **kwargs: Any)

Bases: ToolButton

A toolbar button that acts as a radio button.

Radio tool buttons work in groups where only one button can be active at a time. When one button is activated, all others in the group are automatically deactivated.

__init__(group=None, **kwargs)

Initialize the radio tool button.

Parameters:

• group – Another RadioToolButton to group with, or None for new group

• **kwargs – Additional arguments passed to ToolButton

get_group()

Get the list of buttons in this radio group.

set_group(group_member)

Set the radio group by specifying another member.

Parameters:

group_member – Another RadioToolButton to join groups with

get_active()

Get whether this button is active.

set_active(active)

Set the active state of this button.

Parameters:

active – True to activate, False to deactivate

sugar4.graphics.style module

Style

The style module defines constants for spacing and sizing, as well as classes for Colors and Fonts. Text rendering is handled by Pango and colors are inputted by their HTML code (e.g. #FFFFFF)

All the constants are expressed in pixels. They are defined for the XO screen and are usually adapted to different resolution by applying a zoom factor.

class sugar4.graphics.style.Font(desc: str)

Bases: object

A font defines the style of how the text should be rendered.

This implementation provides integration with Pango font descriptions and CSS styling.

Parameters:

desc (str) – A description of the Font object in Pango format

__init__(desc: str)

__str__() → str

Returns description of font.

get_pango_desc()

Returns Pango description of font. Cached for performance.

get_css_string() → str

Returns a CSS font specification string for modern styling.

class sugar4.graphics.style.Color(color: str, alpha: float = 1.0)

Bases: object

A Color object defines a specific color with RGBA values.

This implementation provides integration with modern color handling and CSS styling.

Parameters:

• color (str) – String in the form #FFFFFF representing the color

• alpha (float) – Transparency of color (0.0 to 1.0)

__init__(color: str, alpha: float = 1.0)

get_rgba() → Tuple[float, float, float, float]

Returns 4-tuple of red, green, blue, and alpha levels in range 0-1.

get_int() → int

Returns color encoded as an int, in the form rgba.

get_gdk_rgba()

Returns GDK RGBA color object for GTK4. This replaces the deprecated get_gdk_color method.

get_gdk_color()

Returns GDK standard color (deprecated in GTK4). Maintained for compatibility.

get_html() → str

Returns string in the standard HTML color format (#FFFFFF).

get_css_rgba() → str

Returns CSS rgba() string for GTK4 styling.

get_svg() → str

Returns HTML formatted color, unless the color is completely transparent, in which case returns “none”.

with_alpha(alpha: float) → Color

Returns a new Color with the specified alpha value.

sugar4.graphics.style.zoom(units: float) → int

Returns size of units pixels at current zoom level.

Parameters:

units (int or float) – Size of item at full size

sugar4.graphics.style.apply_css_to_widget(widget, css: str) → None

Apply CSS styling to a widget.

Parameters:

• widget – Widget to style

• css (str) – CSS string to apply

sugar4.graphics.style.ZOOM_FACTOR = 1.0

Scale factor, as float (eg. 0.72, 1.0)

sugar4.graphics.style.DEFAULT_SPACING = 15

Spacing is placed in-between elements

sugar4.graphics.style.DEFAULT_PADDING = 6

Padding is placed around an element

sugar4.graphics.style.GRID_CELL_SIZE = 75

allow elements to tile neatly within boundaries of a grid http://wiki.sugarlabs.org/go/Human_Interface_Guidelines#The_Grid_System

sugar4.graphics.style.LINE_WIDTH = 2

Thickness of a separator line

sugar4.graphics.style.STANDARD_ICON_SIZE = 55

icon that fits within a grid cell

sugar4.graphics.style.SMALL_ICON_SIZE = 33

small icon, used in palette menu items

sugar4.graphics.style.MEDIUM_ICON_SIZE = 82

larger than standard

sugar4.graphics.style.LARGE_ICON_SIZE = 110

larger than medium, used in journal empty view

sugar4.graphics.style.XLARGE_ICON_SIZE = 151

larger than large, used in activity pulsing launcher icon

sugar4.graphics.style.FONT_SIZE = 10

User’s preferred font size

sugar4.graphics.style.FONT_FACE = 'Sans Serif'

User’s preferred font face

sugar4.graphics.style.FONT_NORMAL = Font('Sans Serif 10.000000')

Normal font

sugar4.graphics.style.FONT_BOLD = Font('Sans Serif bold 10.000000')

Bold font

sugar4.graphics.style.FONT_NORMAL_H = 24

Height in pixels of normal font

sugar4.graphics.style.FONT_BOLD_H = 24

Height in pixels of bold font

sugar4.graphics.style.FONT_ITALIC = Font('Sans Serif italic 10')

Italic font

sugar4.graphics.style.COLOR_BLACK = Color('#000000', alpha=1.0)

Black

sugar4.graphics.style.COLOR_WHITE = Color('#ffffff', alpha=1.0)

White

sugar4.graphics.style.COLOR_TRANSPARENT = Color('#ffffff', alpha=0.0)

Fully transparent color

sugar4.graphics.style.COLOR_PANEL_GREY = Color('#c0c0c0', alpha=1.0)

Default background color of a window

sugar4.graphics.style.COLOR_SELECTION_GREY = Color('#a6a6a6', alpha=1.0)

Background color of selected entry

sugar4.graphics.style.COLOR_TOOLBAR_GREY = Color('#282828', alpha=1.0)

Color of toolbars

sugar4.graphics.style.COLOR_BUTTON_GREY = Color('#808080', alpha=1.0)

Color of buttons

sugar4.graphics.style.COLOR_INACTIVE_FILL = Color('#9d9fa1', alpha=1.0)

Fill colour of an inactive button

sugar4.graphics.style.COLOR_INACTIVE_STROKE = Color('#757575', alpha=1.0)

Stroke colour of an inactive button

sugar4.graphics.style.COLOR_TEXT_FIELD_GREY = Color('#e5e5e5', alpha=1.0)

Background color of entry

sugar4.graphics.style.COLOR_HIGHLIGHT = Color('#e7e7e7', alpha=1.0)

Color of highlighted text

sugar4.graphics.style.COLOR_PRIMARY = Color('#0066cc', alpha=1.0)

Primary accent color

sugar4.graphics.style.COLOR_SUCCESS = Color('#00aa00', alpha=1.0)

Success state color

sugar4.graphics.style.COLOR_WARNING = Color('#ff8800', alpha=1.0)

Warning state color

sugar4.graphics.style.COLOR_ERROR = Color('#cc0000', alpha=1.0)

Error state color

sugar4.graphics.style.PALETTE_CURSOR_DISTANCE = 10

Cursor invoked palettes will be placed this far from the cursor

sugar4.graphics.style.TOOLBAR_ARROW_SIZE = 24

Size of arrow displayed under toolbar buttons

sugar4.graphics.style.MENU_WIDTH_CHARS = 60

Max width of text in a palette menu, in chars

sugar4.graphics.style.BORDER_RADIUS = 8

Default border radius for rounded corners

sugar4.graphics.style.SHADOW_BLUR = 4

Default shadow blur radius

sugar4.graphics.style.TRANSITION_DURATION = 200

Default transition duration in milliseconds

sugar4.graphics.toolbarbox module

ToolbarBox

The ToolbarBox provides a horizontal toolbar container for Sugar activities, supporting both regular toolbar buttons and expandable toolbar sections.

class sugar4.graphics.toolbarbox.ToolbarButton(*args: Any, **kwargs: Any)

Bases: ToolButton

A toolbar button that can expand to show a toolbar page inline.

This is the main difference from regular ToolButton - it can show an entire toolbar page when clicked, similar to a collapsible section.

__init__(page=None, **kwargs)

get_toolbar_box()

property toolbar_box

get_page()

set_page(page)

is_in_palette()

is_expanded()

popdown()

set_expanded(expanded)

do_snapshot(snapshot)

GTK4 drawing implementation with arrow indicator.

class sugar4.graphics.toolbarbox.ToolbarBox(*args: Any, **kwargs: Any)

Bases: Box

A container for toolbars that provides expandable toolbar sections.

The ToolbarBox contains a main horizontal toolbar and can show expanded toolbar pages below it when ToolbarButtons are activated.

__init__(padding=75)

get_toolbar()

property toolbar

get_expanded_button()

set_expanded_button(button)

property expanded_button

get_padding()

set_padding(pad)

sugar4.graphics.toolbox module

Toolbox

A toolbox holds a group of toolbars in a list. One toolbar is displayed at a time. Toolbars are assigned an index and can be accessed using this index. Indices are generated in the order the toolbars are added.

class sugar4.graphics.toolbox.Toolbox(*args: Any, **kwargs: Any)

Bases: Box

Class to represent the toolbox of an activity. Groups a number of toolbars vertically, which can be accessed using their indices. The current toolbar is the only one displayed.

Emits current-toolbar-changed signal when the current toolbar is changed. This signal takes the current page index as an argument.

__init__()

add_toolbar(name: str, toolbar: gi.repository.Gtk.Widget)

Adds a toolbar to this toolbox. Toolbar will be added to the end of this toolbox, and its index will be 1 greater than the previously added index (index will be 0 if it is the first toolbar added).

Parameters:

• name (str) – name of toolbar to be added

• toolbar (Gtk.Widget) – Widget to be appended to this toolbox

remove_toolbar(index: int)

Removes toolbar at the index specified.

Parameters:

index (int) – index of the toolbar to be removed

set_current_toolbar(index: int)

Sets the current toolbar to that of the index specified and displays it.

Parameters:

index (int) – index of toolbar to be set as current toolbar

get_current_toolbar() → int

Returns current toolbar index.

Returns:

Index of current toolbar

Return type:

int

get_toolbar_count() → int

Returns the number of toolbars in this toolbox.

Returns:

Number of toolbars

Return type:

int

get_toolbar_at(index: int) → gi.repository.Gtk.Widget | None

Get the toolbar widget at the specified index.

Parameters:

index (int) – Index of toolbar to retrieve

Returns:

Toolbar widget or None if index is invalid

Return type:

Gtk.Widget

set_toolbar_label(index: int, label: str)

Set the label text for a toolbar tab.

Parameters:

• index (int) – Index of toolbar

• label (str) – New label text

get_toolbar_label(index: int) → str | None

Get the label text for a toolbar tab.

Parameters:

index (int) – Index of toolbar

Returns:

Label text or None if index is invalid

Return type:

str

property current_toolbar: int

Returns current toolbar index.

Returns:

Index of current toolbar

Return type:

int

sugar4.graphics.combobox module

The combobox module provides a combo box; a button like widget which creates a list popup when clicked. It’s best used outside of a toolbar when the user needs to choose from a short list of items.

Example:

class sugar4.graphics.combobox.ComboBox(*args: Any, **kwargs: Any)

Bases: ComboBox

This class provides a simple wrapper based on the Gtk.ComboBox. This lets you make a list of items, with a value, label and optionally an icon.

__init__()

get_value()

The value of the currently selected item; the same as the value argument that was passed to the append_item func.

Returns:

object, value of selected item

append_item(value, text, icon_name=None, file_name=None)

This function adds another item to the bottom of the combo box list.

If either icon_name or file_name are supplied and icon column will be added to the combo box list.

Parameters:

• value (object) – the value that will be returned by get_value, when this item is selected

• text (str) – the user visible label for the item

• icon_name (str) – the name of the icon in the theme to use for this item, optional and conflicting with file_name

• file_name (str) – the path to a sugar (svg) icon to use for this item, optional and conflicting with icon_name

append_separator()

Add a separator to the bottom of the combo box list. The separator can not be selected.

get_active_item()

Get the row of data for the currently selected item.

Returns:

row of data in the format:

[value, text, pixbuf, is_separator]

remove_all()

Remove all list items from the combo box.

sugar4.graphics.toolcombobox module

STABLE.

class sugar4.graphics.toolcombobox.ToolComboBox(*args: Any, **kwargs: Any)

Bases: Box

__init__(combo=None, label_text='', **kwargs)

do_set_property(pspec, value)

set_label_text(text)

Set the label text.

get_label_text()

Get the label text.

sugar4.graphics.toggletoolbutton module

STABLE.

class sugar4.graphics.toggletoolbutton.ToggleToolButton(*args: Any, **kwargs: Any)

Bases: ToggleButton

UI for toggletoolbutton. A ToggleToolButton is a toggle button widget that can be used in toolbars, having an icon, a tooltip palette, and an accelerator. Use ToggleToolButton() to create a new ToggleToolButton.

Parameters:

• accelerator (string) – keyboard shortcut to be used to

• button. (hovers over toggle)

• here (Find about format)

• https – //docs.gtk.org/gtk4/func.accelerator_parse.html

• tooltip (string) – tooltip to be displayed when user

• button.

Keyword Arguments:

icon_name (string) – name of themed icon which is to be used.

__init__(icon_name=None)

set_icon_name(icon_name)

Sets the icon for the tool button from a named themed icon. If it is none then no icon will be shown.

Parameters:

• icon_name (string) – The name for a themed icon.

• too. (It can be set as 'None')

Example

set_icon_name(‘view-radial’)

get_icon_name()

The get_icon_name() method returns the value of the icon_name property that contains the name of a themed icon or None.

create_palette()

get_palette()

set_palette(palette)

get_palette_invoker()

set_palette_invoker(palette_invoker)

set_tooltip(text)

Sets the tooltip of the toogle tool button. Displays when user hovers over the button with cursor.

Parameters:

tooltip (string) – tooltip to be added to the button

set_accelerator(accelerator)

Sets keyboard shortcut that activates this button.

Parameters:

• accelerator (string) – accelerator to be set. Should be in

• <modifier>Letter (form)

• here (Find about format)

• https – //docs.gtk.org/gtk4/func.accelerator_parse.html

Example

set_accelerator(self, ‘accel’)

get_accelerator()

Returns above accelerator string.

do_snapshot(snapshot)

Render the toggle tool button using snapshot-based drawing.

do_clicked()

Implementation method for hiding the tooltip when the toggle button is clicked

sugar4.graphics.toolbutton module

ToolButton

The toolbutton module provides the ToolButton class, which is a Gtk.Button styled as a toolbar button with icon and tooltip for sugar4.

Example

Add a tool button to a window:

from gi.repository import Gtk
from sugar4.graphics.toolbutton import ToolButton

def __clicked_cb(button):
    print("tool button was clicked")

app = Gtk.Application()

def on_activate(app):
    w = Gtk.ApplicationWindow(application=app)
    b = ToolButton(icon_name='dialog-ok', tooltip='a tooltip')
    b.connect('clicked', __clicked_cb)
    w.set_child(b)
    w.present()

app.connect('activate', on_activate)
app.run()

STABLE.

sugar4.graphics.toolbutton.setup_accelerator(tool_button)

class sugar4.graphics.toolbutton.ToolButton(*args: Any, **kwargs: Any)

Bases: Button

The ToolButton class manages a Gtk.Button styled as a toolbar button for sugar4.

This replaces deprecated ToolButton with a modern Button implementation styled to look and behave like a traditional toolbar button.

Parameters:

• icon_name (str, optional) – name of themed icon.

• accelerator (str, optional) – keyboard shortcut to activate this button.

• tooltip (str, optional) – tooltip displayed on hover.

• hide_tooltip_on_click (bool, optional) – Whether tooltip is hidden on click.

__init__(icon_name=None, **kwargs)

set_tooltip(tooltip: str | None)

Set the tooltip.

Parameters:

tooltip (string) – tooltip to be set.

get_tooltip() → str | None

get_hide_tooltip_on_click() → bool

Return True if the tooltip is hidden when a user clicks on the button, otherwise return False.

set_hide_tooltip_on_click(hide_tooltip_on_click: bool)

Set whether or not the tooltip is hidden when a user clicks on the button.

Parameters:

• hide_tooltip_on_click (bool) – True if the tooltip is

• click (hidden on)

• otherwise. (and False)

set_accelerator(accelerator: str | None)

Set accelerator that activates the button.

Parameters:

accelerator (string) – accelerator to be set.

get_accelerator() → str | None

Return accelerator that activates the button.

set_icon_name(icon_name: str | None)

get_icon_name() → str | None

Get the icon name.

Returns:

The icon name or None if no icon is set.

set_icon_widget(icon_widget: gi.repository.Gtk.Widget | None)

Set a custom icon widget.

Parameters:

icon_widget – widget to use as icon.

get_icon_widget() → gi.repository.Gtk.Widget | None

set_label(label: str | None)

get_label() → str | None

create_palette() → Palette | None

get_palette() → Palette | None

Get the current palette.

set_palette(palette: Palette | None)

get_palette_invoker() → ToolInvoker | None

set_palette_invoker(palette_invoker: ToolInvoker | None)

do_snapshot(snapshot)

Render tool button using snapshot-based drawing.

set_active(active: bool)

get_active() → bool

Get the active state of the button.

sugar4.graphics.window module

Window Management

Window management for Sugar activities.

Provides window classes for managing Sugar activity windows with fullscreen support, toolbar management, and tray integration.

Classes:

UnfullscreenButton: Button to exit fullscreen mode Window: Main activity window container

class sugar4.graphics.window.UnfullscreenButton(*args: Any, **kwargs: Any)

Bases: Window

A ready-made “Unfullscreen” button.

Used by Window to exit fullscreen mode using modern window management.

__init__()

connect_button_clicked(callback)

Connect a callback to button click.

class sugar4.graphics.window.Window(*args: Any, **kwargs: Any)

Bases: ApplicationWindow

A Sugar activity window.

Used as a container to display things that happen in an activity. A window contains a canvas widget, and may contain toolbar and tray widgets.

The window layout is:

• toolbar (optional)

• alerts (as overlays)

• canvas (main content)

• tray (optional)

Window supports fullscreen mode where toolbar and tray are hidden.

Key bindings:

• Escape: exit fullscreen mode

• Alt+Space: toggle tray visibility

__init__(**kwargs)

reveal()

Make window active.

Brings the window to the top and makes it active, even after invoking on response to non-GTK events.

is_fullscreen()

Check if the window is fullscreen.

Returns:

window is fullscreen

Return type:

bool

fullscreen()

Make the window fullscreen.

The toolbar and tray will be hidden, and the UnfullscreenButton will be shown for a short time.

unfullscreen()

Restore the window to non-fullscreen mode.

The UnfullscreenButton will be hidden, and the toolbar and tray will be shown.

set_canvas(canvas)

Set canvas widget.

Parameters:

canvas (Gtk.Widget) – the canvas to set

get_canvas()

Get canvas widget.

Returns:

the canvas

Return type:

Gtk.Widget

set_toolbar_box(toolbar_box)

Set toolbar box widget.

Parameters:

toolbar_box (Gtk.Widget) – the toolbar box to set

get_toolbar_box()

Get toolbar box widget.

Returns:

the current toolbar box

Return type:

Gtk.Widget

set_tray(tray, position=gi.repository.Gtk.PositionType.BOTTOM)

Set the tray.

Parameters:

• tray (Gtk.Widget) – the tray to set

• position (Gtk.PositionType) – the edge to set the tray at

add_alert(alert)

Add an alert to the window as an overlay.

Parameters:

alert (Gtk.Widget) – the alert to add

remove_alert(alert)

Remove an alert from the window.

Parameters:

alert (Gtk.Widget) – the alert to remove

set_enable_fullscreen_mode(enable)

Set enable fullscreen mode.

Parameters:

enable (bool) – enable fullscreen mode

get_enable_fullscreen_mode()

Get enable fullscreen mode.

Returns:

enable fullscreen mode

Return type:

bool

property canvas

Get canvas widget.

Returns:

the canvas

Return type:

Gtk.Widget

property toolbar_box

Get toolbar box widget.

Returns:

the current toolbar box

Return type:

Gtk.Widget

sugar4.graphics.xocolor module

XoColor

This class represents all of the colors that the XO can take on. Each pair of colors represents the fill color and the stroke color.

Modern implementation with improved color handling and CSS support.

class sugar4.graphics.xocolor.XoColor(color_string=None)

Bases: object

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")

__init__(color_string=None)

__eq__(other)

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)

Check if two XoColor objects are not equal.

__hash__()

Make XoColor hashable for use in sets and as dict keys.

__str__()

String representation of XoColor.

__repr__()

Detailed string representation of XoColor.

get_stroke_color()

Returns:

stroke color in HTML hex format (#RRGGBB)

Return type:

str

get_fill_color()

Returns:

fill color in HTML hex format (#RRGGBB)

Return type:

str

to_string()

Returns:

formatted string in the format “#STROKEHEX,#FILLHEX”

Return type:

str

classmethod from_string(color_string)

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()

Get a random XO color.

Returns:

Random XoColor instance from the standard palette

Return type:

XoColor

to_rgba_tuple(alpha=1.0)

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

Module contents

Graphics Module

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

class sugar4.graphics.XoColor(color_string=None)

Bases: object

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)

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

__hash__()

Make XoColor hashable for use in sets and as dict keys.

__init__(color_string=None)

__ne__(other)

Check if two XoColor objects are not equal.

__repr__()

Detailed string representation of XoColor.

__str__()

String representation of XoColor.

classmethod from_string(color_string)

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

get_fill_color()

Returns:

fill color in HTML hex format (#RRGGBB)

Return type:

str

classmethod get_random_color()

Get a random XO color.

Returns:

Random XoColor instance from the standard palette

Return type:

XoColor

get_stroke_color()

Returns:

stroke color in HTML hex format (#RRGGBB)

Return type:

str

to_rgba_tuple(alpha=1.0)

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

to_string()

Returns:

formatted string in the format “#STROKEHEX,#FILLHEX”

Return type:

str

class sugar4.graphics.Icon(*args: Any, **kwargs: Any)

Bases: 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

__init__(icon_name: str | None = None, file_name: str | None = None, pixel_size: int = 48, **kwargs)

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

Calculate widget size requirements.

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

Render icon using snapshot-based drawing.

get_alpha() → float

get_badge_name() → str | None

get_badge_size() → int

Get size of badge icon in pixels.

get_file_name() → str | None

get_fill_color() → str | None

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

get_icon_name() → str | None

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

Get pixbuf for this icon.

get_pixel_size() → int

get_scale() → float

get_stroke_color() → str | None

get_xo_color() → XoColor | None

set_alpha(alpha: float)

set_badge_name(badge_name: str | None)

set_file_name(file_name: str | None)

set_fill_color(color: str | None)

set_icon_name(icon_name: str | None)

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

Set pixbuf for this icon.

set_pixel_size(size: int)

set_scale(scale: float)

set_stroke_color(color: str | None)

set_xo_color(xo_color: XoColor | None)

class sugar4.graphics.EventIcon(*args: Any, **kwargs: Any)

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

__init__(**kwargs)

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

Get background color.

get_cache() → bool

Get cache setting.

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

Set background color.

set_cache(cache: bool)

Set cache setting.

class sugar4.graphics.CanvasIcon(*args: Any, **kwargs: Any)

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.

__init__(**kwargs)

do_snapshot(snapshot)

Override to render background based on state.

class sugar4.graphics.CellRendererIcon

Bases: object

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.

__init__()

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

Get rendered surface.

set_file_name(file_name: str)

set_fill_color(color: str)

set_icon_name(icon_name: str)

set_size(size: int)

set_stroke_color(color: str)

set_xo_color(xo_color: XoColor)

sugar4.graphics.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.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 = 48, **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

sugar4.graphics.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