Architecture:Gui Module: Difference between revisions

Latest revision as of 18:04, 12 December 2010

This module contains everything required to create a user interface and is derived from this initial widget implementation.

Widget Set

The general idea of the widget system is to be lean, yet flexible. We do not want to provide as many widgets with as many options as a full blown GUI toolkit, But at the same time, we want to be able to adapt the GUIs style to what fits best to a specific game. To achieve these goals, the implementation is split into a logic and a representation layer that are more or less disjunct. That way, widgets with similar underlying logic (like a toggle button and a check box, or a scroll bar and a progress indicator) can be implemented by a single widget class whose instances get assigned different representations.

Logic Layer

The logic layer is part of the public API and consists of widgets and layouts that all derive from the base widget class. Widgets are single user interface elements like a label, button or text entry field, whereas layouts are containers that can be used to group multiple widgets and define their position on the screen. Toplevel windows or dialogs have to inherit from one of the layout implementations.

Representation Layer

The representation layer is not exposed to the outside and the only hint at its existence is the widget::set_style method, which is used to specify a widgets desired look. Its parameter points to an XML file that describes the look and its elements in a specific format. Internally, a decoration_factory is used to create decorators that take care of rendering the actual widget. Most widgets use the std_decoration that can draw a background and a border.

Window Manager

The window_manager class keeps track of open windows, makes sure they are displayed on screen and receive keyboard or gamepad input. Focus is usually given to the topmost window. The manager also allows fading in and out of windows/dialogs as they are opened or closed.

@@ Line 1: / Line 1: @@
-This module contains everything required to create a user interface and is derived from this initial [[Widget_Set|widget implementation]].
+This module contains everything required to [[Scripting:User Interface|create a user interface]] and is derived from this initial [[Widget_Set|widget implementation]].
+__NOTOC__
+== Widget Set ==
-== Widgets and Layouts ==
+The general idea of the widget system is to be lean, yet flexible. We do not want to provide as many widgets with as many options as a full blown GUI toolkit, But at the same time, we want to be able to adapt the GUIs style to what fits best to a specific game. To achieve these goals, the implementation is split into a logic and a representation layer that are more or less disjunct. That way, widgets with similar underlying logic (like a toggle button and a check box, or a scroll bar and a progress indicator) can be implemented by a single widget class whose instances get assigned different representations.
-The classes of the GUI module are split into widgets and layouts. Widgets are single user interface elements like a label, button or text entry field, whereas layouts are containers that can be used to group multiple widgets and define their position on the screen. Toplevel windows or dialogs have to inherit from one of the layout implementations.
+=== Logic Layer ===
-== Decoration ==
+The logic layer is part of the public API and consists of widgets and layouts that all derive from the base <tt>widget</tt> class. Widgets are single user interface elements like a label, button or text entry field, whereas layouts are containers that can be used to group multiple widgets and define their position on the screen. Toplevel windows or dialogs have to inherit from one of the layout implementations.
-The <tt>decoration</tt> class defines the look of every individual widget. For consistency, widgets of the same type should use the same decoration, but in theory, each widget can have it's own special look. A widgets decoration is described through an XML file that consists of multiple sections:
+=== Representation Layer ===
-  <Data>
+The representation layer is not exposed to the outside and the only hint at its existence is the <tt>widget::set_style</tt> method, which is used to specify a widgets desired look. Its parameter points to an XML file that describes the look and its elements in a specific [[Architecture:Widget Decoration Format|format]]. Internally, a <tt>decoration_factory</tt> is used to create ''decorators'' that take care of rendering the actual widget. Most widgets use the <tt>std_decoration</tt> that can draw a background and a border.
-    <list id="Default" />
-    <list id="Activated" />
-    <list id="Focused" />
-  </Data>
-These currently supported sections are:
-* '''Default''' The standard look of a widget.
-* '''Activated''' A widget that has been activated, like a button that is pressed or a checkbox that has been checked.
-* '''Focused''' An overlay to indicate that the widget has the input focus. Applied over the default or activated look of the widget.
-Each section can contain the following elements, of which '''bg''' and '''has_border''' are mandatory:
-   <string id="bg"></string>
-   <u_int8 id="bg_alpha"></u_int8>
-   <s_int8 id="highlight"></s_int8>
-   <bool id="has_border"></bool>
-   <string id="border_tl"></string>
-   <string id="border_tr"></string>
-   <string id="border_bl"></string>
-   <string id="border_br"></string>
-   <string id="border_top"></string>
-   <string id="border_bot"></string>
-   <string id="border_lft"></string>
-   <string id="border_rgt"></string>
-Their meaning is as follows:
-* '''bg''' The background image. Will be tiled to fill the widget size. If no size is given for the widget, it will assume the size of its background image.
-* '''bg_alpha''' Background translucency from 0 (totally opaque) to 255 (completely transparent).
-* '''highlight''' Brightness adjustment from -127 (very dark) to 127 (very bright). Only valid for section <tt>Focused</tt>.
-* '''has_border''' Whether the widget has a border (1) or not (0). The border is considered part of the widget and will not add to its size. If set to (1), then eight border images must be given: four corner pieces, (t)op(l)eft, (t)op(r)ight, (b)ottom(l)eft and (b)ottom(r)ight as well as 4 edge pieces, (top), (bot)tom, (l)e(ft) and (r)i(g)h(t). The corner pieces are painted as is, whereas the edge pieces are tiled to fill the space between the individual corners.
 == Window Manager ==
-The <tt>window_manager</tt> class keeps track of open windows and dialogs and handles focus, which is usually given to the topmost window. It also allows fading in and out of windows/dialogs as they are opened or closed.
+The <tt>window_manager</tt> class keeps track of open windows, makes sure they are displayed on screen and receive keyboard or gamepad [[Architecture:Input Module|input]]. Focus is usually given to the topmost window. The manager also allows fading in and out of windows/dialogs as they are opened or closed.
 [[Category:Architecture]]
 [[Category:Development]]