|
|
@@ -1,96 +0,0 @@
|
|
|
-==Gui Subsystem==
|
|
|
--------------------------------------------------------------------------------
|
|
|
- - Description
|
|
|
- The Gui subsystem provides an easy way to create in-game windows and populate
|
|
|
- them with widgets.
|
|
|
-
|
|
|
- - The basic Widget:
|
|
|
- Each widget, wether a simple button or a whole complex window, inherit from a
|
|
|
- generic Widget. This class provides the skeleton for the Gui subsystem. It re
|
|
|
- presents a generic 'Gui object' that has a dimension and can be displayed on
|
|
|
- screen. Its functionalities are common to all the derived types and are:
|
|
|
- - Children handling and displaying:
|
|
|
- Each widget contains a list of children widgets, representing a tree as a w
|
|
|
- hole. A widgets belongs to his parent, that can be specified only in the wi
|
|
|
- dget's constructor or by attaching later the widget to a parent if null was
|
|
|
- specified in the constructor, and once set it can't change.
|
|
|
- If no custom method is specified, the drawing of children is performed auto
|
|
|
- matically, otherwise DrawChildren must be called when defining the OnDraw()
|
|
|
- method (usually at the end).
|
|
|
-
|
|
|
- - Mouse interaction:
|
|
|
- Mouse events are received through the On[Preview]Mouse???() method (where
|
|
|
- ??? varies depending on the event being notified). Each mouse event is rece
|
|
|
- ived only if the corresponding action was done inside the widget or one of
|
|
|
- its children. An exception to this is when the widget explicitly captures t
|
|
|
- he mouse: in this case, the widget will receive the mouse events regadrless
|
|
|
- of the fact that they occoured inside or outside the widget itself or one o
|
|
|
- f its children. Of course in this case MouseIn and MouseOut occour only whe
|
|
|
- n the mouse enters or exits the widget that captures the mouse, otherwise t
|
|
|
- hey would not make sense.
|
|
|
-
|
|
|
- - Position and dimension:
|
|
|
- Size and position of widgets can be selected using SetDesiredSize() and Set
|
|
|
- DesiredPosition() methods. Actual values may vary depending on the layout b
|
|
|
- eing used. If values of -1 are specified for the desired size, the layout s
|
|
|
- ystem will interpret it as 'i don't care, you choose', which for default la
|
|
|
- yout means expand the widget as much as possible. Margins, Horizontal and V
|
|
|
- ertical alignment provide a convenient way to handle how widgets are displa
|
|
|
- yed.
|
|
|
-
|
|
|
- - Events:
|
|
|
- Each interaction with the Gui can create an event for the application to resp
|
|
|
- ond.
|
|
|
- There are two kinds of events: OnEvents, and Signals.
|
|
|
- - OnEvents:
|
|
|
- The OnEvents are used by the Gui elements to handle specific behaviours o
|
|
|
- f the elements themselves: for example, a ListView can use the OnPreviewM
|
|
|
- ouseUp (covered later) to detect the selection of a child item. The Progr
|
|
|
- ammer should use these events only when defining custom widgets.
|
|
|
- Some(All?) OnEvents follow the Tunneling-Bubbling pattern:
|
|
|
- When an OnEvent fires, for example an OnMouseMove event, the following pr
|
|
|
- ocedure is followed:
|
|
|
- 1) The element on which the event occours is determined (called Target).
|
|
|
- 2) From the Root Ancestor of the Target, traversing the Widget Tree down
|
|
|
- the branch that leads to the Target, OnPreviewMouseMove is called on e
|
|
|
- ach widget encountered until some of them sets stopPropagation or the
|
|
|
- Target is reached.
|
|
|
- 3) The same procedure is followed, from the Target to the Root Ancestor,
|
|
|
- but this time calling OnMouseMove.
|
|
|
- This mechanism allows parent widgets to be notified of events before the
|
|
|
- Target can know it, allowing them to react accordingly: for example, a Li
|
|
|
- stViewItems listen for OnPreviewMouseUp to detect when they are selected.
|
|
|
- Note: Stopping a Preview event via stopPropagation does not block the cor
|
|
|
- responding Bubbling event to be performed.
|
|
|
-
|
|
|
- - Signals:
|
|
|
- Signals expose a set of events that a Programmer can hook onto to detect
|
|
|
- when a particular User action occours. Each widget has its signals: a Lis
|
|
|
- tView for example, has the SelectionChangedSignal that fires whenever the
|
|
|
- selection changes to another item.
|
|
|
- To attach to a signal, simply define a Slot with the same signature and a
|
|
|
- n handler method and connect it to the desidered signal.
|
|
|
-
|
|
|
- - Layout:
|
|
|
- Its purpose is to give widgets a size and position. It's performed automati
|
|
|
- cally when needed, by means of the OnUpdateLayout event.
|
|
|
- By default, widgets accomodate desired sizes and position requested by the
|
|
|
- children. If a different placement is desired, custom Layout widgets must b
|
|
|
- e used. For example to place a series of button vertically, it's sufficient
|
|
|
- to create a StackLayout widget as child of the container widget, and put th
|
|
|
- e buttons inside it.
|
|
|
-
|
|
|
- - WindowsManager
|
|
|
- The WindowsManager offers an interface between the Crown Entity model and win
|
|
|
- dows. It is the container of all the windows, and is responsible of receiving
|
|
|
- keyboard and mouse events and propagate them in the windows hierarchy.
|
|
|
- Usually the user doesn't need to interface to it except for creation and wind
|
|
|
- dows assignment.
|
|
|
-
|
|
|
- - Window
|
|
|
- It's a specialized Widget that has a title bar, a close button and a client a
|
|
|
- rea where children Widgets are displayed. It is the basic host of all the wid
|
|
|
- gets. This means that non-Window widgets can only exist inside the Widget tre
|
|
|
- e of a Window.
|
|
|
- To insert a widget in the Window client area, just pass them as parent the wi
|
|
|
- dget returned by calling GetClientArea() on the window.
|
Daniele Bartolini