Write docs for constants in sugar3.graphics.style

The constants must be documented, because otherwise they are hidden
from the generated online documentation.

[changes arising from review comments and flake8 compliance]
Signed-off-by: James Cameron <quozl@laptop.org>
This commit is contained in:
Sam Parkinson 2017-04-22 08:26:41 +10:00 committed by James Cameron
parent 17f99a2dbd
commit f17e1a66b4

View File

@ -16,12 +16,13 @@
# Boston, MA 02111-1307, USA. # Boston, MA 02111-1307, USA.
''' '''
The style module defines constants for spacing and sizing, as well as classes for The style module defines constants for spacing and sizing, as well as
Colors and Fonts. Text rendering is handled by Pango and colors are inputted by their classes for Colors and Fonts. Text rendering is handled by Pango and
HTML code (e.g. #FFFFFFFF) colors are inputted by their HTML code (e.g. #FFFFFFFF)
All the constants are expressed in pixels. They are defined for the XO screen All the constants are expressed in pixels. They are defined for the XO
and are usually adapted to different resolution by applying a zoom factor. screen and are usually adapted to different resolution by applying a
zoom factor.
''' '''
import os import os
@ -115,8 +116,8 @@ class Color(object):
def _html_to_rgb(self, html_color): def _html_to_rgb(self, html_color):
''' '''
Converts and returns (r, g, b) tuple in float format from standard HTML format (#FFFFFF). Converts and returns (r, g, b) tuple in float format from
Colors will be in range 0-1 standard HTML format (#FFFFFF). Colors will be in range 0-1
Args: Args:
html_color (string): html string in the format #FFFFFF html_color (string): html string in the format #FFFFFF
@ -136,8 +137,8 @@ class Color(object):
def get_svg(self): def get_svg(self):
''' '''
Returns HTML formatted color, unless the color is completely transparent, in Returns HTML formatted color, unless the color is completely
which case returns "none" transparent, in which case returns "none"
''' '''
if self._a == 0.0: if self._a == 0.0:
@ -156,52 +157,82 @@ def zoom(units):
return int(ZOOM_FACTOR * units) return int(ZOOM_FACTOR * units)
ZOOM_FACTOR = _compute_zoom_factor() ZOOM_FACTOR = _compute_zoom_factor() #: scale factor, as float (eg. 0.72, 1.0)
DEFAULT_SPACING = zoom(15) DEFAULT_SPACING = zoom(15) #: Spacing is placed in-between elements
DEFAULT_PADDING = zoom(6) DEFAULT_PADDING = zoom(6) #: Padding is placed around an element
#: allow elements to tile neatly within boundaries of a grid
#: http://wiki.sugarlabs.org/go/Human_Interface_Guidelines#The_Grid_System
GRID_CELL_SIZE = zoom(75) GRID_CELL_SIZE = zoom(75)
LINE_WIDTH = zoom(2)
LINE_WIDTH = zoom(2) #: Thickness of a separator line
#: icon that fits within a grid cell
STANDARD_ICON_SIZE = zoom(55) STANDARD_ICON_SIZE = zoom(55)
#: small icon, used in palette menu items
SMALL_ICON_SIZE = zoom(33) SMALL_ICON_SIZE = zoom(33)
#: larger than standard
MEDIUM_ICON_SIZE = zoom(55 * 1.5) MEDIUM_ICON_SIZE = zoom(55 * 1.5)
#: larger than medium, used in journal empty view
LARGE_ICON_SIZE = zoom(55 * 2.0) LARGE_ICON_SIZE = zoom(55 * 2.0)
#: larger than large, used in activity pulsing launcher icon
XLARGE_ICON_SIZE = zoom(55 * 2.75) XLARGE_ICON_SIZE = zoom(55 * 2.75)
if 'org.sugarlabs.font' in Gio.Settings.list_schemas(): if 'org.sugarlabs.font' in Gio.Settings.list_schemas():
settings = Gio.Settings('org.sugarlabs.font') settings = Gio.Settings('org.sugarlabs.font')
#: User's preferred font size
FONT_SIZE = settings.get_double('default-size') FONT_SIZE = settings.get_double('default-size')
#: User's preferred font face
FONT_FACE = settings.get_string('default-face') FONT_FACE = settings.get_string('default-face')
else: else:
#: User's preferred font size
FONT_SIZE = 10 FONT_SIZE = 10
#: User's preferred font face
FONT_FACE = 'Sans Serif' FONT_FACE = 'Sans Serif'
#: Normal font
FONT_NORMAL = Font('%s %f' % (FONT_FACE, FONT_SIZE)) FONT_NORMAL = Font('%s %f' % (FONT_FACE, FONT_SIZE))
#: Bold font
FONT_BOLD = Font('%s bold %f' % (FONT_FACE, FONT_SIZE)) FONT_BOLD = Font('%s bold %f' % (FONT_FACE, FONT_SIZE))
#: Height in pixels of normal font
FONT_NORMAL_H = zoom(24) FONT_NORMAL_H = zoom(24)
#: Height in pixels of bold font
FONT_BOLD_H = zoom(24) FONT_BOLD_H = zoom(24)
# old style toolbox design
TOOLBOX_SEPARATOR_HEIGHT = zoom(9) TOOLBOX_SEPARATOR_HEIGHT = zoom(9)
TOOLBOX_HORIZONTAL_PADDING = zoom(75) TOOLBOX_HORIZONTAL_PADDING = zoom(75)
TOOLBOX_TAB_VBORDER = int((zoom(36) - FONT_NORMAL_H - FOCUS_LINE_WIDTH) / 2) TOOLBOX_TAB_VBORDER = int((zoom(36) - FONT_NORMAL_H - FOCUS_LINE_WIDTH) / 2)
TOOLBOX_TAB_HBORDER = zoom(15) - FOCUS_LINE_WIDTH - _TAB_CURVATURE TOOLBOX_TAB_HBORDER = zoom(15) - FOCUS_LINE_WIDTH - _TAB_CURVATURE
TOOLBOX_TAB_LABEL_WIDTH = zoom(150 - 15 * 2) TOOLBOX_TAB_LABEL_WIDTH = zoom(150 - 15 * 2)
COLOR_BLACK = Color('#000000') COLOR_BLACK = Color('#000000') #: Black
COLOR_WHITE = Color('#FFFFFF') COLOR_WHITE = Color('#FFFFFF') #: White
#: Fully transparent color
COLOR_TRANSPARENT = Color('#FFFFFF', alpha=0.0) COLOR_TRANSPARENT = Color('#FFFFFF', alpha=0.0)
#: Default background color of a window
COLOR_PANEL_GREY = Color('#C0C0C0') COLOR_PANEL_GREY = Color('#C0C0C0')
#: Background color of selected entry
COLOR_SELECTION_GREY = Color('#A6A6A6') COLOR_SELECTION_GREY = Color('#A6A6A6')
#: Color of toolbars
COLOR_TOOLBAR_GREY = Color('#282828') COLOR_TOOLBAR_GREY = Color('#282828')
#: Color of buttons
COLOR_BUTTON_GREY = Color('#808080') COLOR_BUTTON_GREY = Color('#808080')
#: Fill colour of an inactive button
COLOR_INACTIVE_FILL = Color('#9D9FA1') COLOR_INACTIVE_FILL = Color('#9D9FA1')
#: Stroke colour of an inactive button
COLOR_INACTIVE_STROKE = Color('#757575') COLOR_INACTIVE_STROKE = Color('#757575')
#: Background color of entry
COLOR_TEXT_FIELD_GREY = Color('#E5E5E5') COLOR_TEXT_FIELD_GREY = Color('#E5E5E5')
#: Color of highlighted text
COLOR_HIGHLIGHT = Color('#E7E7E7') COLOR_HIGHLIGHT = Color('#E7E7E7')
#: Cursor invoked palettes will be placed this far from the cursor
PALETTE_CURSOR_DISTANCE = zoom(10) PALETTE_CURSOR_DISTANCE = zoom(10)
#: Size of arrow displayed under toolbar buttons to represent their status
TOOLBAR_ARROW_SIZE = zoom(24) TOOLBAR_ARROW_SIZE = zoom(24)
#: Max width of text in a palette menu, in chars
MENU_WIDTH_CHARS = 60 MENU_WIDTH_CHARS = 60