Cafu Engine
Window.hpp
1 /*
2 Cafu Engine, http://www.cafu.de/
3 Copyright (c) Carsten Fuchs and other contributors.
4 This project is licensed under the terms of the MIT license.
5 */
6 
7 #ifndef CAFU_GUISYS_WINDOW_HPP_INCLUDED
8 #define CAFU_GUISYS_WINDOW_HPP_INCLUDED
9 
10 #include "CompBasics.hpp"
11 #include "CompTransform.hpp"
12 #include "Templates/Array.hpp"
13 #include "Templates/Pointer.hpp"
14 
15 #include <climits>
16 
17 
18 struct CaKeyboardEventT;
19 struct CaMouseEventT;
20 struct lua_State;
21 struct luaL_Reg;
22 namespace cf { namespace TypeSys { class TypeInfoT; } }
23 namespace cf { namespace TypeSys { class TypeInfoManT; } }
24 namespace cf { namespace TypeSys { class CreateParamsT; } }
25 namespace cf { namespace TypeSys { class MethsDocT; } }
26 
27 
28 namespace cf
29 {
30  namespace GuiSys
31  {
32  class ComponentBaseT;
33  class GuiImplT;
34  class WindowCreateParamsT;
35 
36 
37  /// The TypeInfoTs of all WindowT derived classes must register with this TypeInfoManT instance.
38  cf::TypeSys::TypeInfoManT& GetWindowTIM();
39 
40 
41  /**
42  * This class represents a window of the GuiSys.
43  * A WindowT is the most basic element of a GUI, and all other windows are derived and/or combined from this.
44  *
45  * WindowT instances can be created in C++ code or in Lua scripts, using the gui:new() function.
46  * They can be passed from C++ code to Lua and from Lua to C++ code at will.
47  * In C++ code, all WindowT instances are kept in IntrusivePtrT's. Their lifetime is properly managed:
48  * A window is deleted automatically when it is no longer used in Lua \emph{and} in C++.
49  * That is, code like
50  * Example 1: w=gui:new("WindowT"); gui:SetRootWindow(w); w=nil;
51  * Example 2: w=gui:new("WindowT"); w:AddChild(gui:new("WindowT"));
52  * works as expected. See the cf::ScriptBinderT class for technical and implementation details.
53  */
54  class WindowT : public RefCountedT
55  {
56  public:
57 
58  /// The normal constructor.
59  /// @param Params The creation parameters for the window.
60  WindowT(const WindowCreateParamsT& Params);
61 
62  /// The copy constructor.
63  /// Copies a window (optionally with all of its children recursively).
64  /// The parent of the copy is always NULL and it is up to the caller to put the copy into a window hierarchy.
65  /// @param Window The window to construct this window from.
66  /// @param Recursive Whether to recursively copy all children.
67  WindowT(const WindowT& Window, bool Recursive=false);
68 
69  /// The virtual copy constructor.
70  /// Callers can use this method to create a copy of this window without knowing its concrete type.
71  /// Overrides in derived classes use a covariant return type to facilitate use when the concrete type is known.
72  /// @param Recursive Whether to recursively clone all children of this window.
73  virtual WindowT* Clone(bool Recursive=false) const;
74 
75  /// The virtual destructor. Deletes this window and all its children.
76  virtual ~WindowT();
77 
78 
79  GuiImplT& GetGui() const { return m_Gui; }
80 
81  /// Returns the parent window of this window.
82  IntrusivePtrT<WindowT> GetParent() const { return m_Parent; }
83 
84  /// Returns the immediate children of this window.
85  /// This is analogous to calling GetChildren(Chld, false) with an initially empty Chld array.
86  const ArrayT< IntrusivePtrT<WindowT> >& GetChildren() const { return m_Children; }
87 
88  /// Returns the children of this window.
89  /// @param Chld The array to which the children of this window are appended. Note that Chld gets *not* initially cleared by this function!
90  /// @param Recurse Determines if also the grand-children, grand-grand-children etc. are returned.
91  void GetChildren(ArrayT< IntrusivePtrT<WindowT> >& Chld, bool Recurse=false) const;
92 
93  /// Adds the given window to the children of this window, and sets this window as the parent of the child.
94  ///
95  /// This method also makes sure that the name of the Child is unique among its siblings,
96  /// modifying it as necessary. See SetName() for more details.
97  ///
98  /// @param Child The window to add to the children of this window.
99  /// @param Pos The position among the children to insert the child window at.
100  /// @returns true on success, false on failure (Child has a parent already, or is the root of this window).
101  bool AddChild(IntrusivePtrT<WindowT> Child, unsigned long Pos=0xFFFFFFFF);
102 
103  /// Removes the given window from the children of this window.
104  /// @param Child The window to remove from the children of this window.
105  /// @returns true on success, false on failure (Child is not a child of this window).
107 
108  /// Returns the top-most parent of this window, that is, the root of the hierarchy this window is in.
109  IntrusivePtrT<WindowT> GetRoot(); // Method cannot be const because return type is not const -- see implementation.
110 
111 
112  /// Returns the application component of this window.
113  /// This component is much like the "Basics" and "Transform" components, but it can be set by the
114  /// application (see SetApp()), and is intended for the sole use by the application, e.g. for
115  /// implementing a "selection gizmo" in the GUI Editor.
117 
118  /// The `const` variant of the GetApp() method above. See GetApp() for details.
119  IntrusivePtrT<const ComponentBaseT> GetApp() const { return m_App; }
120 
121  /// Sets the application component for this window. See GetApp() for details.
123 
124  /// Returns the "Basics" component of this window.
125  /// The "Basics" component defines the name and the "show" flag of the window.
126  IntrusivePtrT<ComponentBasicsT> GetBasics() const { return m_Basics; }
127 
128  /// Returns the "Transform" component of this window.
129  /// The "Transform" component defines the position, size and orientation of the window.
130  IntrusivePtrT<ComponentTransformT> GetTransform() const { return m_Transform; }
131 
132 
133  /// Returns the components that this window is composed of.
134  /// Only the "custom" components are returned, does *not* include the application component,
135  /// "Basics" or "Transform".
136  const ArrayT< IntrusivePtrT<ComponentBaseT> >& GetComponents() const { return m_Components; }
137 
138  /// Returns the (n-th) component of the given (type) name.
139  /// Covers the "custom" components as well as the application components, "Basics" and "Transform".
140  /// That is, `GetComponent("Basics") == GetBasics()` and `GetComponent("Transform") == GetTransform()`.
141  IntrusivePtrT<ComponentBaseT> GetComponent(const std::string& TypeName, unsigned int n=0) const;
142 
143  /// Adds the given component to this window.
144  ///
145  /// @param Comp The component to add to this window.
146  /// @param Index The position among the other components to insert `Comp` at.
147  /// @returns `true` on success, `false` on failure (if `Comp` is part of a window already).
148  bool AddComponent(IntrusivePtrT<ComponentBaseT> Comp, unsigned long Index=ULONG_MAX);
149 
150  /// Deletes the component at the given index from this window.
151  void DeleteComponent(unsigned long CompNr);
152 
153 
154  /// Returns the position of the upper left corner of this window in absolute (vs. relative to the parent) coordinates.
155  Vector2fT GetAbsolutePos() const;
156 
157  /// Finds the window with the name WantedName in the hierachy tree of this window.
158  /// Use GetRoot()->Find("xy") in order to search the entire GUI for the window with name "xy".
159  /// @param WantedName The name of the window that is to be found.
160  /// @returns The pointer to the desired window, or NULL if no window with this name exists.
161  IntrusivePtrT<WindowT> Find(const std::string& WantedName); // Method cannot be const because return type is not const -- see implementation.
162 
163  /// Finds the topmost window that contains the point `Pos` in the hierachy tree of this window
164  /// (with `Pos` being in (absolute) screen coordinates, *not* relative to this window).
165  /// Use `GetRoot()->Find(Pos)` in order to search the entire GUI for the window containing the point `Pos`.
166  /// @param Pos The coordinate of the point to test.
167  /// @param OnlyVisible If true, only visible windows are reported. If false, all windows are searched.
168  /// @returns The pointer to the desired window, or NULL if there is no window that contains `Pos`.
169  IntrusivePtrT<WindowT> Find(const Vector2fT& Pos, bool OnlyVisible=true); // Method cannot be const because return type is not const -- see implementation.
170 
171  /// Renders this window.
172  /// Note that this method does *not* setup any of the MatSys's model, view or projection matrices: it's up to the caller to do that!
173  virtual void Render() const;
174 
175  /// Keyboard input event handler.
176  /// @param KE Keyboard event.
177  virtual bool OnInputEvent(const CaKeyboardEventT& KE);
178 
179  /// Mouse input event handler.
180  /// @param ME Mouse event.
181  /// @param PosX Mouse position x.
182  /// @param PosY Mouse position y.
183  virtual bool OnInputEvent(const CaMouseEventT& ME, float PosX, float PosY);
184 
185  /// The clock-tick event handler.
186  /// @param t The time in seconds since the last clock-tick.
187  virtual bool OnClockTickEvent(float t);
188 
189  /// Calls the Lua method with name `MethodName` of this window.
190  /// This method is analogous to GuiI::CallLuaFunc(), see there for more details.
191  /// @param MethodName The name of the lua method to call.
192  /// @param Signature DOCTODO
193  bool CallLuaMethod(const char* MethodName, const char* Signature="", ...);
194 
195 
196  // The TypeSys related declarations for this class.
197  virtual const cf::TypeSys::TypeInfoT* GetType() const { return &TypeInfo; }
198  static void* CreateInstance(const cf::TypeSys::CreateParamsT& Params);
199  static const cf::TypeSys::TypeInfoT TypeInfo;
200 
201 
202  protected:
203 
204  // Methods called from Lua scripts on cf::GuiSys::WindowTs.
205  // They are protected so that derived window classes can access them when implementing overloads.
206  static int AddChild(lua_State* LuaState);
207  static int RemoveChild(lua_State* LuaState);
208  static int GetParent(lua_State* LuaState);
209  static int GetChildren(lua_State* LuaState);
210  static int GetTime(lua_State* LuaState);
211  static int GetBasics(lua_State* LuaState);
212  static int GetTransform(lua_State* LuaState);
213  static int AddComponent(lua_State* LuaState);
214  static int RmvComponent(lua_State* LuaState);
215  static int GetComponents(lua_State* LuaState);
216  static int GetComponent(lua_State* LuaState);
217  static int toString(lua_State* LuaState);
218 
219  static const luaL_Reg MethodsList[]; ///< List of methods registered with Lua.
220  static const char* DocClass;
221  static const cf::TypeSys::MethsDocT DocMethods[];
222  static const cf::TypeSys::MethsDocT DocCallbacks[];
223 
224 
225  private:
226 
227  void operator = (const WindowT&); ///< Use of the Assignment Operator is not allowed.
228 
229  GuiImplT& m_Gui; ///< The GUI instance in which this window was created and exists. Useful in many regards, but especially for access to the underlying Lua state.
230  WindowT* m_Parent; ///< The parent of this window. May be NULL if there is no parent. In order to not create cycles of IntrusivePtrT's, the type is intentionally a raw pointer only.
231  ArrayT< IntrusivePtrT<WindowT> > m_Children; ///< The list of children of this window.
232  float m_Time; ///< This windows local time (starting from 0.0).
233  IntrusivePtrT<ComponentBaseT> m_App; ///< A component for the sole use by the application / implementation.
234  IntrusivePtrT<ComponentBasicsT> m_Basics; ///< The component that defines the name and the "show" flag of this window.
235  IntrusivePtrT<ComponentTransformT> m_Transform; ///< The component that defines the position, size and orientation of this window.
236  ArrayT< IntrusivePtrT<ComponentBaseT> > m_Components; ///< The components that this window is composed of.
237  };
238  }
239 }
240 
241 #endif
IntrusivePtrT< const ComponentBaseT > GetApp() const
The const variant of the GetApp() method above. See GetApp() for details.
Definition: Window.hpp:119
This class implements smart (reference-counted) pointers.
Definition: Pointer.hpp:43
IntrusivePtrT< ComponentTransformT > GetTransform() const
Returns the "Transform" component of this window.
Definition: Window.hpp:130
IntrusivePtrT< ComponentBaseT > GetComponent(const std::string &TypeName, unsigned int n=0) const
Returns the (n-th) component of the given (type) name.
Definition: Window.cpp:221
bool RemoveChild(IntrusivePtrT< WindowT > Child)
Removes the given window from the children of this window.
Definition: Window.cpp:165
const ArrayT< IntrusivePtrT< WindowT > > & GetChildren() const
Returns the immediate children of this window.
Definition: Window.hpp:86
virtual bool OnInputEvent(const CaKeyboardEventT &KE)
Keyboard input event handler.
Definition: Window.cpp:376
IntrusivePtrT< ComponentBaseT > GetApp()
Returns the application component of this window.
Definition: Window.hpp:116
This struct describes a mouse event.
Definition: OpenGLWindow.hpp:185
bool AddComponent(IntrusivePtrT< ComponentBaseT > Comp, unsigned long Index=ULONG_MAX)
Adds the given component to this window.
Definition: Window.cpp:252
virtual bool OnClockTickEvent(float t)
The clock-tick event handler.
Definition: Window.cpp:419
const ArrayT< IntrusivePtrT< ComponentBaseT > > & GetComponents() const
Returns the components that this window is composed of.
Definition: Window.hpp:136
This class manages the type infos.
Definition: TypeSys.hpp:145
This class implements a Graphical User Interface (GUI).
Definition: GuiImpl.hpp:42
void SetApp(IntrusivePtrT< ComponentBaseT > App)
Sets the application component for this window. See GetApp() for details.
Definition: Window.cpp:211
This struct describes a keyboard event.
Definition: OpenGLWindow.hpp:20
WindowT(const WindowCreateParamsT &Params)
The normal constructor.
Definition: Window.cpp:51
This class represents a window of the GuiSys.
Definition: Window.hpp:54
virtual void Render() const
Renders this window.
Definition: Window.cpp:338
Vector2fT GetAbsolutePos() const
Returns the position of the upper left corner of this window in absolute (vs. relative to the parent)...
Definition: Window.cpp:280
virtual WindowT * Clone(bool Recursive=false) const
The virtual copy constructor.
Definition: Window.cpp:109
IntrusivePtrT< WindowT > GetParent() const
Returns the parent window of this window.
Definition: Window.hpp:82
IntrusivePtrT< ComponentBasicsT > GetBasics() const
Returns the "Basics" component of this window.
Definition: Window.hpp:126
Creation parameters for a GUI window.
Definition: WindowCreateParams.hpp:21
IntrusivePtrT< WindowT > Find(const std::string &WantedName)
Finds the window with the name WantedName in the hierachy tree of this window.
Definition: Window.cpp:300
void DeleteComponent(unsigned long CompNr)
Deletes the component at the given index from this window.
Definition: Window.cpp:267
static const luaL_Reg MethodsList[]
List of methods registered with Lua.
Definition: Window.hpp:219
virtual ~WindowT()
The virtual destructor. Deletes this window and all its children.
Definition: Window.cpp:115
bool AddChild(IntrusivePtrT< WindowT > Child, unsigned long Pos=0xFFFFFFFF)
Adds the given window to the children of this window, and sets this window as the parent of the child...
Definition: Window.cpp:146
IntrusivePtrT< WindowT > GetRoot()
Returns the top-most parent of this window, that is, the root of the hierarchy this window is in...
Definition: Window.cpp:200
Definition: Renderer.hpp:16
Definition: TypeSys.hpp:52
Definition: TypeSys.hpp:57
This class keeps type information (about an entity class that occurs in the game).
Definition: TypeSys.hpp:79
bool CallLuaMethod(const char *MethodName, const char *Signature="",...)
Calls the Lua method with name MethodName of this window.
Definition: Window.cpp:436
A base class for objects that are reference-counted with IntrusivePtrTs.
Definition: Pointer.hpp:13