Common widget operations - the BaseWidget

Common widget operations - the BaseWidget
Prev		Next

The BaseWidget is the most basic class of all widgets and contains common attributes and methods, each widget of the ocempui.widgets module has to include. Every widget inherits from it, so that any description and explanation in this section also to the widgets, which are explained later on.

Positioning and sizing

A widget can be set to a specific position on the main screen using the topleft attribute.

widget.topleft = 10, 15

Using the above code, the topleft corner of the widget will bo positioned at the x-coordinate 10 and the y-coordinate 15 of the main screen, of which 0, 0 denotes the topleft corner.

Note

This will not work as supposed using widgets, that are bound to a Container or Bin widget, which will be explained in one of the following sections.

If you read the current topleft value of a widget, keep in mind, that it will return a tuple containing the both, x and y, coordinates.

Every widget supports a minimum size, that will be respected by the default drawing methods.

widget.minsize = 80, 20

The minimum size is the guaranteed width and height, the widget should occupy on the screen. It can grow beyond that minimum size, if this is needed to display all of its contents according to its drawing method, but will never be smaller than this value.

The currently used width and height, which can differ from its minsize can be retrieved using the width and height attributes or as tuple using the size.

if (widget.width == widget.minsize[0]) and (widget.height == widget.minsize[1]):
    print "Widget does not exceed its minimum size."

The counterpart to the minsize attribute is maxsize. A widget will never grow beyond the values of it, if set.

Note

The BaseWidget class exports all pygame.Rect attributes, so you are not limited to the topleft only, but can also use the pygame.Rect attributes you are used to. See the pygame.Rect documentation for more details.

Keyboard support

To allow an easy and logical keyboard navigation, widgets have an index attribute, which influences the navigation order using the keyboard.

widget.index = 3

A lower index will cause the widget to receive the input focus earlier. It is highly recommended, that you set this value in your own code to provide the user a better keyboard accessibility.

The input focus mentioned above denotes a state of the widget, in which the user can interact with it using the keyboard only. A Button widget will react upon pressing the space bar with a click while an Entry widget will let the user type text. You can set the input focus of a widget manually with the focus attribute.

widget.focus = True

This however will not work with any widget (e.g. layout containers such as the Table). Dependant on the widget the set_focus() method of it will return either True or False, which indicates, that the input focus could be sucessfully set for that widget or not.

frame = VFrame ()
focusok = frame.set_focus (True)
if not focusok:
    print "Focus could not be set."

Other features

Widgets can be disabled from user interaction and receiving events, if you set their sensitive attribute to False.

widget.sensitive = False

They will be set in a different state then to indicate, that the user cannot interact with them anymore. Of course you can reset the sensitivity at any time.

The renderering system of the ocempgui.widgets module can use different layers, on which widgets are drawn. This is especially useful and often necessary to place widgets above others (e.g. to place a Window widget above another one).

widget.depth = 3

The above code causes the widget to be drawn above all widgets, which have a depth value smaller than three, but under any widget, that has a higher depth. You can find an example demonstrating this in the section called “Window”. The layer feature is described in detail in the section called “The layer and indexing system”.

Widgets support transparency using the alpha color channel. To set it for a widget use the opacity attribute of it. The opacity attribute accepts values betwee 0 (fully transparent) and 255 (not transparent, default).

widget.opacity = 100

To change the appearance of a single widget instance, the create_style() method and style attribute of a widget can be used. While create_style() will generate an instance specific style dictionary for the widget, style can be used to have quick access to it, once it is created.

# Create an instance specific style dictionary for the widget and return a
# reference to it.
style = widget.create_style()
...

# Access the created style dictionary of the widget.
widget.style[...] = ...

To avoid unnecessary overhead, the style attribute of a widget will not be set to anything by default. It will be filled with something useful on th first invocation of create_style().

Changing instance specific styles is explained in detail in the section called “Changing the appearance of single instances”.

Prev		Next
Widget overview	Home	Labels