sugar3.graphics.icon module¶

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.

Designing a Sugar Icon¶

If you want to make an icon to use in Sugar, start by designing something in a vector program, like Inkscape. When you are designing the icon, use a canvas that is 55x55px.

When designing your icon, use 2 colors. For example, use a black stroke and a white fill color. You need to keep this consistent and remember those colors.

You should also keep the subcell grid in mind when designing the icon. A grid cell (which the size of an icon) is made up of 5 by 5 subcells. To use this in Inkscape, enable the page grid (View -> Page Grid), the go to grid properties (File -> Document Properties -> Grids). In grid properties, set the “Spacing X” option to 11, “Spacing Y” to 11 and “Major grid line every” to 1.

Before your icon is ready to be used in Sugar, it needs to be Sugarized. This converts the colors to SVG entities, which allows Sugar to change the colors of the icon. To do that, just run the sugar-iconify script. Usually, it “just works” like:

python path/to/sugar-iconify.py -o icon.svg

Code Example¶

Example of using icons with badges:

from gi.repository import Gtk

from sugar3.graphics.icon import EventIcon
from sugar3.graphics.icon import Icon
from sugar3.graphics import style
from sugar3.graphics.xocolor import XoColor
from sugar3.graphics.palette import Palette

import common


test = common.Test()
test.show()

box = Gtk.Box(orientation=Gtk.Orientation.VERTICAL)
test.pack_start(box, True, True, 0)
box.show()

# An XO Icon, normal size, setting the color via the XoColor object
icon = Icon(icon_name='computer-xo',
            pixel_size=style.STANDARD_ICON_SIZE,
            xo_color=XoColor('#00BEFF,#FF7800'))
box.pack_start(icon, False, False, 0)
icon.show()

# You can mix constructor keyword argument and setting
# properties after creation
icon = EventIcon(icon_name='network-wireless-080',
                 pixel_size=style.STANDARD_ICON_SIZE)
# Badges are little icons displayed
icon.props.badge_name = 'emblem-favorite'
# Instead of using the XoColor, you can use any SVG color specifier:
icon.props.fill_color = 'rgb(230, 0, 10)'
icon.props.stroke_color = '#78E600'
# Unlike normal icons, EventIcons support palettes:
icon.props.palette = Palette('Hello World')
box.pack_start(icon, False, False, 0)
icon.show()


if __name__ == '__main__':
    common.main(test)

Badge Icons¶

Badge icons are small icons that are attached to the normal icon. For example, a WiFi network icon might have a star badge attached to the bottom left corner (the “attach point”) that indicates that the network is connected to.

Badge icons are displayed at _BADGE_SIZE percent (45% currently), of their main icon.

Badge icons are specified by the icon name, in the same sense that normal icons have a Icon.set_icon_name function.

Attach Points¶

Where the badge icon is placed is defined by the main icon. By default, it is centered on 0, 0. That means that the 3 quarters of the icon will be cut off! Therefore, it is helpful to define the attach points.

When Sugar loads the main icon, it looks for a .icon file. For example, if the icon path is resolved to /theme/computer-xo.svg, the /theme/computer-xo.icon will be tried to find the attach points.

The .icon files are to be formatted as follows:

[Icon Data]
AttachPoints=970,850

In this example, the badge will be centered at 97.0% on the X axis, and 85.0% on the Y axis.

class sugar3.graphics.icon.CanvasIcon(**kwargs)¶

Bases: sugar3.graphics.icon.EventIcon

An EventIcon with active and prelight states, and a styleable background. If the icon pops up a palette, the prelight state is set until the palette pops down. This is used to render a light grey highlight, however can be configured by Gtk+ CSS with the :prelight selector.

Care should to use connect_to_palette_pop_events for all palettes created and shown around this icon.

connect_to_palette_pop_events(palette)¶

Connect to the palette’s popup and popdown events, so that the prelight state is set at the right times. You should run this call before you EventIcon.set_palette or before you return from your EventIcon.create_palette function, eg:

def create_palette(self):
palette = …

self.connect_to_palette_pop_events(palette) return palette

Parameters: palette (sugar3.graphics.palette.Palette) – palette to connect

do_draw(cr)¶: Gtk widget implementation method

class sugar3.graphics.icon.CellRendererIcon(treeview=None)¶

Bases: gi.repository.Gtk.CellRenderer

background_color¶

connect_to_scroller(scrolled)¶

create_palette()¶

do_activate(event, widget, path, background_area, cell_area, flags)¶: activate(self, event:Gdk.Event, widget:Gtk.Widget, path:str, background_area:Gdk.Rectangle, cell_area:Gdk.Rectangle, flags:Gtk.CellRendererState) -> bool

do_get_property(pspec)¶

do_get_size(widget, cell_area, x_offset=None, y_offset=None, width=None, height=None)¶: get_size(self, widget:Gtk.Widget, cell_area:Gdk.Rectangle=None) -> x_offset:int, y_offset:int, width:int, height:int

do_render(cr, widget, background_area, cell_area, flags)¶: render(self, cr:cairo.Context, widget:Gtk.Widget, background_area:Gdk.Rectangle, cell_area:Gdk.Rectangle, flags:Gtk.CellRendererState)

do_set_property(pspec, value)¶

do_start_editing(event, widget, path, background_area, cell_area, flags)¶: start_editing(self, event:Gdk.Event=None, widget:Gtk.Widget, path:str, background_area:Gdk.Rectangle, cell_area:Gdk.Rectangle, flags:Gtk.CellRendererState) -> Gtk.CellEditable or None

file_name¶

fill_color¶

get_xo_color()¶

icon_name¶

is_scrolling()¶

prelit_fill_color¶

prelit_stroke_color¶

set_background_color(value)¶

set_file_name(value)¶

set_fill_color(value)¶

set_icon_name(value)¶

set_prelit_fill_color(value)¶

set_prelit_stroke_color(value)¶

set_size(value)¶

set_stroke_color(value)¶

set_xo_color(value)¶

size¶

stroke_color¶

xo_color¶

class sugar3.graphics.icon.EventIcon(**kwargs)¶

Bases: gi.repository.Gtk.EventBox

An Icon class that provides access to mouse events and that can act as a cursor-positioned palette invoker.

The palette invoker can be used in 3 ways:

Set the palette during your constructor, see set_palette
Override the create_palette method, see create_palette
Set the tooltip, see create_tooltip

Otherwise, the icon setup api is the same as the basic Icon. This EventIcon class supports the icon_name, stroke_color, fill_color, file_name, xo_color, pixel_size, scale and alpha keyword arguments as the Icon. The added arguments are as follows:

Keyword Arguments

background_color (Gdk.Color) – the color to draw the icon on top of. It defaults to None, which means no background is drawn (transparent). The alpha channel of the Gdk.Color is disregarded.
cache (bool) – if True, the icon file contents will be cached to reduce disk usage
palette (sugar3.graphics.palette.Palette) – a palette to connect

alpha¶

background_color¶: event_icon.props.get_background_color -> see set_background_color and get_background_color

badge_name¶

cache¶: event_icon.props.cache -> see set_cache and get_cache

create_palette()¶

The create_palette function is called when the palette needs to be invoked. For example, when the user has right clicked the icon or the user has hovered over the icon for a long time.

The create_palette will only be called once or zero times. The palette returned will be stored and re-used if the user invokes the palette multiple times.

Your create_palette implementation does not need to Gtk.Widget.show the palette, as this will be done by the invoker. However, you still need to show the menu items, etc that you place in the palette.

Returns: sugar3.graphics.palette.Palette, or None to indicate that you do not want a palette shown

The default implementation returns None, to indicate no palette should be shown.

do_draw(cr)¶: Gtk widget implementation method

do_get_preferred_height()¶: Gtk widget implementation method

do_get_preferred_width()¶: Gtk widget implementation method

do_get_property(pspec)¶

do_set_property(pspec, value)¶

file_name¶

fill_color¶

get_background_color()¶

Returns: Gdk.Color, current background color, may be None

get_badge_name()¶

get_cache()¶

Returns: bool, if the icon file will be saved in the LRU

get_file_name()¶

get_fill_color()¶

get_icon_name()¶

get_palette()¶: Gets the current palette, either set by set_palette or cached after a call to create_palette

get_palette_invoker()¶

get_scale()¶

get_size()¶

get_stroke_color()¶

icon_name¶

palette¶: event_icon.props.palette -> see get_palette and set_palette

palette_invoker¶

pixel_size¶

scale¶

set_alpha(alpha)¶

set_background_color(value)¶

Parameters: value (Gdk.Color) – color use as background (alpha is ignored), or None meaning no background is drawn (transparent)

set_badge_name(value)¶

set_cache(value)¶

Sugar caches icon file contents in a smart cache. Currently, we use a LRU (Least Recently Used) algorithm to manage the cache.

Parameters: value (bool) – if True, the icon file will be cached in the LRU

set_file_name(value)¶

set_fill_color(value)¶

set_icon_name(value)¶

set_palette(palette)¶

Sets the palette to show. If the palette is not None, this will override the palette set by create_palette.

Parameters: palette (sugar3.graphics.palette.Palette) – palette or None

set_palette_invoker(palette_invoker)¶

set_scale(value)¶

set_size(value)¶

set_stroke_color(value)¶

set_tooltip(text)¶

Creates a palette with the tooltip text. This will override any current palette set through set_palette or that will ever be returned by create_palette.

Parameters: text (str) – tooltip text

set_xo_color(value)¶

stroke_color¶

xo_color¶

class sugar3.graphics.icon.Icon(**kwargs)¶

Bases: gi.repository.Gtk.Image

The most basic Sugar icon class. Displays the icon given.

You must set either the file_name, file or icon_name properties, otherwise, no icon will be visible.

You should set the pixel_size, using constants the *_ICON_SIZE constants from sugar3.graphics.style module.

You should set the color (either via xo_color or fill_color and stroke_color), otherwise the default black and white fill and stroke will be used.

Keyword Arguments

file_name (str) – a path to the SVG icon file
file (object) – same behaviour as file_name, but for sugar3.util.TempFilePath type objects
icon_name (str) – a name of an icon in the theme to display. The icons in the theme include those in the sugar-artwork project and icons in the activity’s ‘/icons’ directory
pixel_size (int) – size of the icon, in pixels. Best to use the constants from sugar3.graphics.style, as those constants are scaled based on the user’s preferences
xo_color (sugar3.graphics.xocolor.XoColor) – color to display icon, a shortcut that just sets the fill_color and stroke_color
fill_color (str) – a string, like ‘#FFFFFF’, that will serve as the fill color for the icon
stroke_color (str) – a string, like ‘#282828’, that will serve as the stroke color for the icon
icon_size – deprecated since 0.102.0, use pixel_size instead
badge_name (str) – the icon_name for a badge icon, see set_badge_name
alpha (float) – transparency of the icon, defaults to 1.0

alpha¶: icon.props.alpha -> see set_alpha, note no getter

badge_name¶: icon.props.badge_name -> see get_badge_name and set_badge_name

do_draw(cr)¶: Gtk widget implementation method

do_get_preferred_height()¶: Gtk widget implementation method

do_get_preferred_width()¶: Gtk widget implementation method

do_get_property(pspec)¶

do_set_property(pspec, value)¶

file¶

fill_color¶: icon.props.fill_color -> see get_fill_color and set_fill_color

get_badge_name()¶

Get the badge name, as set by set_badge_name

Returns: str, badge icon name

get_badge_size()¶

Returns: int, size of badge icon, in pixels

get_file()¶

get_fill_color()¶

Get the color used to fill the icon

Returns: str, SVG color string, like ‘#FFFFFF’

get_pixbuf()¶

Returns the GdkPixbuf.Pixbuf for the icon, if one has been loaded yet. If the icon has been drawn (do_draw), the icon will be loaded.

The pixbuf only contains the SVG icon that has been loaded and recoloured. It does not contain the badge.

get_stroke_color()¶

Get the color used to paint the icon stroke

Returns: str, SVG color string, like ‘#282828’

pixbuf¶: icon.props.pixbuf -> see get_pixbuf and set_pixbuf

scale¶: icon.props.scale -> see set_scale, note no getter

set_alpha(value)¶

Set the transparency for the icon. Defaults to 1.0, which is fully visible icon.

Parameters: value (float) – alpha value from 0.0 to 1.0

set_badge_name(value)¶

See the Badge Icons section at the top of the file.

Parameters: value (str) – the icon name for the badge

set_file(file_name)¶

set_fill_color(value)¶

Set the color used to fill the icon

Parameters: value (str) – SVG color string, like ‘#FFFFFF’

set_pixbuf(pixbuf)¶

Set the pixbuf. This will force the icon to be rendered with the given pixbuf. The icon will still be centered, badge added, etc.

Parameters: pixbuf (GdkPixbuf.Pixbuf) – pixbuf to set

set_scale(value)¶

Scales the icon, with the transformation origin at the top left corner. Note that this only scales the resulting drawing, so at large scales the icon will appear pixilated.

Parameters: value (float) – new scaling factor

set_stroke_color(value)¶

Set the color used to paint the icon stroke

Parameters: value (str) – SVG color string, like ‘#282828’

set_xo_color(value)¶

Set the colors used to display the icon

Parameters: value (sugar3.graphics.xocolor.XoColor) – new XoColor to use

stroke_color¶: icon.props.stroke_color -> see get_stroke_color and set_stroke_color

xo_color¶: icon.props.xo_color -> see set_xo_color, note there is no getter

sugar3.graphics.icon.get_icon_file_name(icon_name)¶

Resolves a given icon name into a file path. Looks for any icon in them theme, including those in sugar-artwork and those in the activities ‘/icons/’ directory.

Returns: str, path to icon, or None is the icon is not found in the theme

sugar3.graphics.icon.get_icon_state(base_name, perc, step=5)¶

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

First, you need a set of icons. They must be prefixed with base_name, for example “network-wireless”. They must be suffixed with 3 digit percentage numbers, for example “-000”, “-200”, etc. Eventually, you get a collection of icon names like:

network-wireless-000
network-wireless-020
network-wireless-040
network-wireless-060
network-wireless-080
network-wireless-100

All of these icons must be placed in the icon theme, such that they are addressable by their icon_name.

Parameters

base_name (str) – base icon name, eg network-wireless
perc (float) – desired percentage between 0 and 100, eg. 67.8

Keyword Arguments

step (int) –

step to increment to find all possible icons

From the example above, we could step 5, because 0, 5, 10, 15, etc, includes all number suffixes in our set of icons (0, 20, 40, etc).

If we had the number suffixes 0, 33, 66, 99, we could not use 5, as none of the numbers are divisible by 5.

Returns

str, icon name that represent given state, or None if not found

sugar3.graphics.icon.get_surface(**kwargs)¶

Get cairo surface of the icon. Supports the same arguments as Icon, in exactly the same way.

Returns: cairo surface or None if image was not found

sugar3.graphics.icon module¶

Designing a Sugar Icon¶

Code Example¶

Badge Icons¶

Attach Points¶

Sugar Toolkit GTK3

Navigation

Related Topics