Type Style

object --+
         |
        Style

Style () -> Style

Style class for drawing objects.

Style definitions
-----------------
Styles are used to change the appearance of the widgets. The drawing
methods of the Style class will use the specific styles of the
'styles' attribute to change the fore- and background colors, font
information and border settings of the specific widgets. The styles
are set using the lower lettered classname of the widget to draw.
Additionally the Style class supports cascading styles by falling
back to the next available class name in the widget its __mro__
list. If no specific set style could be found for the specific
widget type, the Style class will use the 'default' style entry of
its 'styles' dictionary.

Any object can register its own style definition and request it
using the correct key. A Button widget for example, could register
its style definition this way:

Style.styles['button'] = WidgetStyle ({ .... })

Any other button widget then will use this style by default, so
their look is all the same.

It is also possible to pass an own type dictionary to the drawing
methods of the attached engine class in order to get a surface,
which can be shown on the screen then:

own_style = WidgetStyle ({ ... })
surface = style.engine.draw_rect (width, height, own_style)

If the style should be based on an already existing one, the
copy_style() method can be used to retrieve a copy to work with
without touching the orignal one:

own_style = style.copy_style (my_button.__class__)

The BaseWidget class offers a get_style() method, which will copy
the style of the widget class to the specific widget instance. Thus
you can safely modify the instance specific style for the widget
without touching the style for all widgets of that class.

The style dictionaries registered within the 'styles' dictionary of
the Style class need to match some prerequisites to be useful. On
the one hand they need to incorporate specific key-value pairs,
which can be evaluated by the various drawing functions, on the
other they need to have some specific key-value pairs, which are
evaluated by the Style class.

The following lists give an overview about the requirements the
style dictionaries have to match, so that the basic Style class can
work with them as supposed.

Style entries
-------------
The registered style WidgetStyle dictionaries for the widgets need
to contain key-value pairs required by the functions of the
referenced modules. The following key-value pairs are needed to
create the surfaces:

bgcolor = WidgetStyle ({ STATE_TYPE : color, ... })

The background color to use for the widget surface.

fgcolor = WidgetStyle ({ STATE_TYPE : color, ... })

The foreground color to use for the widget. This is also the text
color for widgets, which will display text.

lightcolor = WidgetStyle ({ STATE_TYPE : color, ... })
darkcolor = WidgetStyle ({ STATE_TYPE : color, ... })

Used to create shadow border effects on several widgets. The color
values usually should be a bit brighter or darker than the bgcolor
values.

bordercolor = WidgetStyle ({ STATE_TYPE : color, ... })

Also used to create border effects on several widgets. In contrast
to the lightcolor and darkcolor entries, this is used, if flat
borders (BORDER_FLAT) have to drawn.

shadowcolor = (color1, color2)

The colors to use for dropshadow effects. The first tuple entry will
be used as inner shadow (near by the widget), the second as outer
shadow value.

image = WidgetStyle ({ STATE_TYPE : string })

Pixmap files to use instead of the background color. If the file is
not supplied or cannot be loaded, the respective bgcolor value is
used.

font = WidgetStyle ({ 'name' : string, 'size' : integer,
                      'alias' : integer, 'style' : integer })

Widgets, which support the display of text, make use of this
key-value pair. The 'name' key denotes the font name ('Helvetica')
or the full path to a font file ('/path/to/Helvetica.ttf').  'size'
is the font size to use. 'alias' is interpreted as boolean value for
antialiasing. 'style' is a bit-wise combination of FONT_STYLE_TYPES
values as defined in ocempgui.draw.Constants and denotes additional
rendering styles to use.

shadow = integer

The size of the 3D border effect for a widget.

IMPORTANT: It is important to know, that the Style class only
supports a two-level hierarchy for styles. Especially the
copy_style() method is not aware of style entries of more than two
levels. This means, that a dictionary in a style dictionary is
possible (as done in the 'font' or the various color style entries),
but more complex style encapsulations are unlikely to work
correctly.
Some legal examples for user defined style entries:

style['ownentry'] = 99                        # One level
style['ownentry'] = { 'foo' : 1, 'bar' : 2 }  # Two levels: level1[level2]

This one however is not guaranteed to work correctly and thus should
be avoided:

style['ownentry'] = { 'foo' : { 'bar' : 1, 'baz' : 2 }, 'foobar' : { ... }}

Dicts and WidgetStyle
---------------------

OcempGUI uses a WidgetStyle dictionary class to keep track of
changes within styles and to update widgets on th fly on changing
those styles. When you are creating new style files (as explained in
the next section) you do not need to explicitly use the
WidgetStyle() dictionary, but can use plain dicts instead. Those
will be automatically replaced by a WidgetStyle on calling load().

You should however avoid using plain dicts if you are modifying
styles of widgets or the Style class at run time and use a
WidgetStyle instead:

# generate_new_style() returns a plain dict.
style = generate_new_style ()
button.style = WidgetStyle (style)

Style files
-----------
A style file is a key-value pair association of style entries for
widgets. It can be loaded and used by the Style.load() method to set
specific themes and styles for the widgets. The style files use the
python syntax and contain key-value pairs of style information for
the specific widgets. The general syntax looks like follows:

widgetclassname = WidgetStyle ({ style_entry : { value } })

An example style file entry for the Button widget class can look
like the following:

button = { 'bgcolor' :{ STATE_NORMAL : (200, 100, 0) },
           'fgcolor' : { STATE_NORMAL : (255, 0, 0) },
           'shadow' : 5 }

The above example will set the bgcolor[STATE_NORMAL] color style
entry for the button widget class to (200, 100, 0), the
fgcolor[STATE_NORMAL] color style entry to (255, 0, 0) and the
'shadow' value for the border size to 5. Any other value of the
style will remain untouched.

Loading a style while running an application does not have any
effect on widgets

* with own styles set via the BaseWidget.get_style() method,
* already drawn widgets using the default style.

The latter ones need to be refreshed via the set_dirty()/update()
methods explicitly to make use of the new style.

Style files allow user-defined variables, which are prefixed with an
underscore. A specific color thus can be stored in a variable to allow
easier access of it.

_red = (255, 0, 0)
___myown_font = 'foo/bar/font.ttf'

Examples
--------
The OcempGUI module contains a file named 'default.rc' in the themes
directory of the installation, which contains several style values
for the default appearance of the widgets. Additional information
can be found in the manual of OcempGUI, too.

Attributes:
styles - A dictionary with the style definitions of various elements.
engine - The drawing engine, which takes care of drawing elements.