Graphics API: Difference between revisions

From OLPC
Jump to navigation Jump to search
No edit summary
 
(11 intermediate revisions by 4 users not shown)
Line 1: Line 1:
== Colors ==
== Colors ==


{|border=1 cellpadding=3 cellspacing=0 style="border: 1px #666666 solid; border-collapse: collapse; background: #f9f9f9;"
; Black : palettes, popups
!style="background:#cccccc;"|Name!!style="background:#cccccc;"|Primary Uses!!style="background:#cccccc;"|Hex!!style="background:#cccccc;"|% Gray
; Toolbar Grey #262626 : toolbars, expanded palette
|-
; Button Grey #808080 : buttons
|Black||Palettes, popups||#000000||100%
; Selection Grey #A6A6A6 : selection, expanded panels
|-
; Panel Grey #C0C0C0 : panel, desktop
|Toolbar Grey||Toolbars, Trays, Palette Groupings||#404040||75%
; Text field Grey #E5E5E5 : text field background
|-
; White : pressed states and multiline text areas
|Button Grey||Default Button States||#808080||50%
|-
|Selection Grey||Selections, Panel Groupings||#A6A6A6||35%
|-
|Panel Grey||Panels, Desktop||#C0C0C0||25%
|-
|Text Field Grey||Text entry background||#E5E5E5||10%
|-
|White||Pressed states, multiline text areas||#FFFFFF||0%
|}


== States ==
== States ==


{|border=1 cellpadding=3 cellspacing=0 style="border: 1px #666666 solid; border-collapse: collapse; background: #f9f9f9;"
; Default : gtk.STATE_NORMAL
!style="background:#cccccc;"|Sugar State!!style="background:#cccccc;"|GTK Equivalent!!style="background:#cccccc;"|Description
; Focused : gtk.STATE_SELECTED
|-
; Pressed : gtk.STATE_ACTIVE
|Default||gtk.STATE_NORMAL||The default state of the control; it is active (accepts interaction) but isn't presently being interacted with
; Hover : gtk.STATE_PRELIGHT
|-
; Inactive : gtk.STATE_INSENSITIVE
|Focused||gtk.STATE_SELECTED||The focused state; all focused controls have a rounded rectangle surrounding stroke; text controls have white background
|-
|Pressed||gtk.STATE_ACTIVE||The control is pressed
|-
|Hover||gtk.STATE_PRELIGHT||The control is beneath the mouse; generally reserved for a few specific buttons
|-
|Inactive||gtk.STATE_INSENSITIVE||The control is inactive, eg. not accepting any form of interaction
|}


== Activity ==
== Activity ==
Line 23: Line 41:
The high level activity view, inherits from Window. Example code for a stock activity:
The high level activity view, inherits from Window. Example code for a stock activity:


import gtk
'''
from gettext import gettext as _
class WriteActivity(activity.Activity):
from sugar.activity import activity
class FoobarActivity(activity.Activity):
def __init__(self, handle, browser=None):
def __init__(self, handle, browser=None):
activity.Activity.__init__(self, handle)
activity.Activity.__init__(self, handle)
Line 31: Line 52:
toolbar = gtk.Toolbar()
toolbar = gtk.Toolbar()
toolbox.add_toolbar(_('Write'), toolbar)
toolbox.add_toolbar(_('Foobar'), toolbar)
toolbar.show()
toolbar.show()
self.set_toolbox(toolbox)
self.set_toolbox(toolbox)
toolbox.show()
editor = Editor()
# editor = Editor()
self.set_canvas(editor)
# self.set_canvas(editor)
editor.show()
# editor.show()
'''


== Window ==
== Window ==


sugar.graphics.window
<tt>sugar.graphics.window</tt>


* Support canvas, toolbox and panel elements and layout them correctly.
* Support canvas, toolbox and panel elements and layout them correctly.
Line 49: Line 70:
== Button ==
== Button ==


gtk.Button
<tt>gtk.Button</tt>


* The image should work the same of the image button
* The image should work the same as the image button
* Need to write a theme to match the visual style
* Need a theme to match the visual style
* Cancel should never be default because you can always activate it with Esc
* Cancel button should never be the default because you can always activate it with Esc
* Radius should be 1/2 of the control height
* Radius should be 1/2 of the control height
* Write a list of stock icons people should use and replace them in the theme to match our visual style
* Write a list of stock icons people should use and replace them in the theme to match our visual style
Line 59: Line 80:
== Icon ==
== Icon ==


sugar.graphics.Icon
<tt>sugar.graphics.Icon</tt>


* Used in canvas-like views so probably an Hippo item.
* Used in canvas-like views, so probably a Hippo item.
* Svg only (Must easily support dynamic colorization with xo colors)
* Svg Only.
* Always has a Rollover Palette
* It should support xo colors easily.
* Rollovers with a focus mark.
* Upon rollover it has a white, stroked, rounded rectangle focus mark


== Toolbox ==
== Toolbox ==
Line 76: Line 97:
sugar.graphics.IconButton
sugar.graphics.IconButton


* Support for SVG and png.
* Support both SVG and PNG formats; recommend SVG
* Icons should be grey scale. But might be coloured with the XO colors (svg only)
* Icons should be grayscale, but might accept XO colors (SVG only)
* Size of the button is 75 pixels, size of the icon canvas is 55 and suggested icon size is around 45.
* Size of the button is 75px, size of the icon canvas is 55px, and suggested icon size is approx. 45px.
* States, defaults:
* States, defaults:


Hover : Black
Hover : 75px rectangle, black fill
Pressed : Rounded rectangle 61 pixels, 10 pixels of radius, filled in selection grey
Pressed : 61px Rounded rectangle, 10px radius, selection grey fill
Focused : Rounded rectangle 61 pixels, 10 pixels of radius, stroked in white 2.25 points
Focused : 61px Rounded rectangle, 10px radius, white 2.25pt stroke
Inactive. Fallbacks if no inactive icon is specified.
Inactive (Fallbacks if no inactive icon is specified):
Svg: Remove the fill and render the stroke in button grey
Svg: Remove the fill and render the stroke in button grey
Png: just do some effect on the pixbuf, which also work for grey icons
Png: just do some effect on the pixbuf, which also work for grey icons


* You can set an icon for each states which replace the default except for the Hover state of buttons which has rollover.
* Icons may be specified for each state which overrides the deaults; Hover state of buttons with Rollover Palettes cannot be overidden.
* "palette" boolean property. If true show an arrow active immediately on click (but also on hover)
* Define a "palette" boolean property. When true, show an arrow and make the button action reveal the palette immediately on click (but also on hover as usual)


== IconButton ==
== IconButton ==


sugar.graphics.IconButton
<tt>sugar.graphics.IconButton</tt>


* Support for rollovers
* Support for Rollover Palettes
* Contains IconButton
* Contains IconButton
* There is no palette but a tooltip.
* When there is no Rollover Palette attached, it should have a tooltip.
* Normal: Button grey rounded filled rectangle
* Normal: Button grey rounded filled rectangle
* Inactive: Button grey rounded stroked rectangle
* Inactive: Button grey rounded stroked rectangle
Line 245: Line 266:
== GroupBox ==
== GroupBox ==


sugar.GroupBox
<tt>sugar.GroupBox</tt>


* just a container
* just a container
* set_title and set_title_widget (checkbox, radiobutton...)
* set_title and set_title_widget (checkbox, radiobutton...)
* different color and separator under title
* different color (depends on container, either palette or panel), separator beneath title


== TreeView ==
== TreeView ==
Line 277: Line 298:
* Secondary states appear after a delay, or with a single click on the icon.
* Secondary states appear after a delay, or with a single click on the icon.
* Secondary disappears with the esc key, clicking outside the popup or clicking on a button inside.
* Secondary disappears with the esc key, clicking outside the popup or clicking on a button inside.

== IconEntry ==
The sugar.graphics.IconEntry is a SexyIconEntry from Libsexy, see http://www.chipx86.com/wiki/Libsexy


[[Category:API]]
[[Category:API]]
[[Category:Sugar]]
[[Category:Developers]]

Latest revision as of 10:32, 14 November 2007

Colors

Name Primary Uses Hex % Gray
Black Palettes, popups #000000 100%
Toolbar Grey Toolbars, Trays, Palette Groupings #404040 75%
Button Grey Default Button States #808080 50%
Selection Grey Selections, Panel Groupings #A6A6A6 35%
Panel Grey Panels, Desktop #C0C0C0 25%
Text Field Grey Text entry background #E5E5E5 10%
White Pressed states, multiline text areas #FFFFFF 0%

States

Sugar State GTK Equivalent Description
Default gtk.STATE_NORMAL The default state of the control; it is active (accepts interaction) but isn't presently being interacted with
Focused gtk.STATE_SELECTED The focused state; all focused controls have a rounded rectangle surrounding stroke; text controls have white background
Pressed gtk.STATE_ACTIVE The control is pressed
Hover gtk.STATE_PRELIGHT The control is beneath the mouse; generally reserved for a few specific buttons
Inactive gtk.STATE_INSENSITIVE The control is inactive, eg. not accepting any form of interaction

Activity

sugar.activity.Activity

The high level activity view, inherits from Window. Example code for a stock activity:

import gtk
from gettext import gettext as _
from sugar.activity import activity

class FoobarActivity(activity.Activity):
    def __init__(self, handle, browser=None):
        activity.Activity.__init__(self, handle)

        toolbox = activity.ActivityToolbox(self)

        toolbar = gtk.Toolbar()
        toolbox.add_toolbar(_('Foobar'), toolbar)
        toolbar.show()

        self.set_toolbox(toolbox)
        toolbox.show()

        # editor = Editor()
        # self.set_canvas(editor)
        # editor.show()

Window

sugar.graphics.window

  • Support canvas, toolbox and panel elements and layout them correctly.

Button

gtk.Button

  • The image should work the same as the image button
  • Need a theme to match the visual style
  • Cancel button should never be the default because you can always activate it with Esc
  • Radius should be 1/2 of the control height
  • Write a list of stock icons people should use and replace them in the theme to match our visual style

Icon

sugar.graphics.Icon

  • Used in canvas-like views, so probably a Hippo item.
  • Svg only (Must easily support dynamic colorization with xo colors)
  • Always has a Rollover Palette
  • Upon rollover it has a white, stroked, rounded rectangle focus mark

Toolbox

sugar.graphics.Toolbox

  • Supports multiple toolbars in tabs

IconButton

sugar.graphics.IconButton

  • Support both SVG and PNG formats; recommend SVG
  • Icons should be grayscale, but might accept XO colors (SVG only)
  • Size of the button is 75px, size of the icon canvas is 55px, and suggested icon size is approx. 45px.
  • States, defaults:
   Hover : 75px rectangle, black fill
   Pressed : 61px Rounded rectangle, 10px radius, selection grey fill
   Focused : 61px Rounded rectangle, 10px radius, white 2.25pt stroke
   Inactive (Fallbacks if no inactive icon is specified):
       Svg: Remove the fill and render the stroke in button grey
       Png: just do some effect on the pixbuf, which also work for grey icons
  • Icons may be specified for each state which overrides the deaults; Hover state of buttons with Rollover Palettes cannot be overidden.
  • Define a "palette" boolean property. When true, show an arrow and make the button action reveal the palette immediately on click (but also on hover as usual)

IconButton

sugar.graphics.IconButton

  • Support for Rollover Palettes
  • Contains IconButton
  • When there is no Rollover Palette attached, it should have a tooltip.
  • Normal: Button grey rounded filled rectangle
  • Inactive: Button grey rounded stroked rectangle

ToggleIconButton

sugar.graphics.ToggleIconButton

  • Toggled should be like Pressed
  • Inconsistent should be the same of Default (the action depend on the cases)
  • Pressed state and Toggled state is Selection grey

ToolIconButton

sugar.graphics.ToolIconButton

  • Contains a ToggleIconButton

CheckButton

gtk.CheckButton

  • Match the visual design, should be possible with just theme changes

RadioButton

gtk.RadioButton

  • Exactly like CheckButton just a different indicator

ComboBox

gtk.ComboBox

  • Match the visual style. Hopefully only theme changes.
  • Add the scroll thing.
  • Groups. Either by a normal separator or a titled separator.
  • Optional support for showing just the icon from the menu (maybe, low priority)
  • Allow fixed sizing of the "button" and ellipsize the label

Entry

gtk.Entry

  • Support for packing icons before and after the entry. Extend gtk.Entry.
  • Activate/Cancel functionality. Two buttons at the end to the entry and key bindings (Esc and Enter). They are visible only when there are changes. The icons appear only when the field is focused and the content is changed since it gained focus. When hitting escape revert and select all the text.

ComboBoxEntry

gtk.ComboxBoxEntry

  • We miss accept/cancel functionality. Probably patch gtk to allow to replace the entry in the combo box with sugar.Entry.

SearchEntry

sugar.graphics.SearchEntry

  • Use sugar.Entry
  • Search button on the left. Clicking should focus the entry.
  • Cancel button (Esc) on the right, always visible when there is text in the entry. Clicking it will clear the text and focus the textfield.
  • Activate button (Enter) on the right displayed when the content of the text field changed from the last focus or activation.
  • While activating:
   the Activate button becomes a Spinner.
   clicking the close button also cancel the search.
  • When activation is completed:
   The spinner goes away.
   We *don't* clear the entry but we select the text.
  • Search can either be incremental or on activation. For incremental there is no Accept button. start_spinning and stop_spinning to control the spin icon. start would only spin for an amount of time decided by the widget itself (and documented).
  • The suggestions list is provided by the application. Need to figure out which api to use, either model or signal based.
  • Default implementation of suggestions which automatically save the latest searches.

DateSelector

sugar.graphics.DateSelector sugar.graphics.DateComboBox (lower priority)

  • Pluggable calendar implementation to support different kind of calendars (localization).
  • Might reuse gtk.Calendar. We should unify month/year selectors and accellerate the movement gradually.

SpinButton

gtk.SpinButton

  • Make it match the visual design, hopefully just theme changes

ToolItem

gtk.ToolItem or sugar.graphics.ToolItem (the API will be kept very similar)

  • Optional label, either text or icon
  • Used for example to have a label near a SpinButton. Clicking on the label should focus the spin button.

ProgressBar

gtk.ProgressBar

  • Make it match the visual design, hopefully just theme changes.
  • For determinate progress bars should we always pulse to show that there is activity (power consumption? necessary feedback?)
  • Do not use text inside the progress bar

Spinner

sugar.graphics.Spinner

  • pulse() call to keep it running with a timeout
  • stop()

Slider

gtk.Range

  • Property to show the fill in white color, probably default on.
  • Draw the discrete steps.
  • For colored sliders, subclass gtk.Range and add a gradient.

LevelIndicator

sugar.graphics.LevelIndicator

  • Set the number of blocks
  • Set the level as percentage
  • Property for discrete or not
  • We can probably use a GtkAdjustment for most of the above.Rollovers

TextView

gtk.TextView

ScrolledWindow

gtk.ScrolledWindow

  • Theme it to match the visual.

sugar.ScrolledWindow

  • Support for markers. Line as default and optional support for other shapes (star for bookmarks, circles for xos...). Generic way of add marks and keep them updated (observer?)

Expander

gtk.Expander

Separator

gtk.Separator

GroupBox

sugar.GroupBox

  • just a container
  • set_title and set_title_widget (checkbox, radiobutton...)
  • different color (depends on container, either palette or panel), separator beneath title

TreeView

gtk.TreeView

Notebook

gtk.Notebook

  • Expand to fill the whole space by default but property to turn it off
  • Switching tabs with the little arrows should page

Palette

sugar.graphics.Palette

  • Inmediately on rollover, show the black background.
  • After a very short delay, show the primary state (name of the action and key shortcut).
  • After a bigger delay, show the popup secondary state.
  • Could be animated.
  • Menu Items would go on the top and then the free-form rollover content.
  • The popup would be a gtk.Window that contains a Label, a MenuShell, an hippo.Canvas (or whatever) and finally a button bar (OK/Cancel).
  • The popup will have a setPrimaryState(label, accelerator) method. For action buttons would be a MenuItem, for the others would only be a Label.
  • The primary state should already have the same width as the secondary state and the expandable areas.
  • Primary states appear and disappear automatically (with a short delay). A click outside makes it disappear instantly.
  • Secondary states appear after a delay, or with a single click on the icon.
  • Secondary disappears with the esc key, clicking outside the popup or clicking on a button inside.

IconEntry

The sugar.graphics.IconEntry is a SexyIconEntry from Libsexy, see http://www.chipx86.com/wiki/Libsexy