source/gui/CGUI.h

   1 /* Copyright (C) 2013 Wildfire Games.
   2  * This file is part of 0 A.D.
   3  *
   4  * 0 A.D. is free software: you can redistribute it and/or modify
   5  * it under the terms of the GNU General Public License as published by
   6  * the Free Software Foundation, either version 2 of the License, or
   7  * (at your option) any later version.
   8  *
   9  * 0 A.D. is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  * GNU General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU General Public License
  15  * along with 0 A.D.  If not, see <http://www.gnu.org/licenses/>.
  16  */
  17
  18 /*
  19 CGUI
  20
  21 --Overview--
  22
  23         This is the top class of the whole GUI, all objects
  24         and settings are stored within this class.
  25
  26 --More info--
  27
  28         Check GUI.h
  29
  30 */
  31
  32 #ifndef INCLUDED_CGUI
  33 #define INCLUDED_CGUI
  34
  35 //--------------------------------------------------------
  36 //  Includes / Compiler directives
  37 //--------------------------------------------------------
  38 // NOTE: GUI.h included at the bottom of this file (has to be after CGUI class
  39 // definition)
  40
  41 #include "GUITooltip.h"
  42 #include "GUIbase.h"
  43
  44 #include "ps/Overlay.h" // CPos and CRect
  45
  46 #include "lib/input.h"
  47
  48 #include "ps/XML/Xeromyces.h"
  49
  50 #include <boost/unordered_set.hpp>
  51
  52 //--------------------------------------------------------
  53 //  Macros
  54 //--------------------------------------------------------
  55
  56 //--------------------------------------------------------
  57 //  Types
  58 //--------------------------------------------------------
  59
  60 //--------------------------------------------------------
  61 //  Error declarations
  62 //--------------------------------------------------------
  63
  64 ERROR_TYPE(GUI, JSOpenFailed);
  65
  66 //--------------------------------------------------------
  67 //  Declarations
  68 //--------------------------------------------------------
  69
  70 /**
  71  * Contains a list of values for new defaults to objects.
  72  */
  73 struct SGUIStyle
  74 {
  75         // A list of defaults for
  76         std::map<CStr, CStrW> m_SettingsDefaults;
  77 };
  78
  79 struct JSObject; // The GUI stores a JSObject*, so needs to know that JSObject exists
  80 class IGUIObject;
  81 class CGUISpriteInstance;
  82 struct SGUIText;
  83 struct CColor;
  84 struct SGUIText;
  85 struct SGUIIcon;
  86 class CGUIString;
  87 class CGUISprite;
  88 struct SGUIImageEffects;
  89 struct SGUIScrollBarStyle;
  90 class GUITooltip;
  91
  92 /**
  93  * The main object that represents a whole GUI page.
  94  *
  95  * No interfacial functions throws.
  96  */
  97 class CGUI
  98 {
  99         NONCOPYABLE(CGUI);
 100
 101         friend class IGUIObject;
 102         friend class IGUIScrollBarOwner;
 103         friend class CInternalCGUIAccessorBase;
 104
 105 private:
 106         // Private typedefs
 107         typedef IGUIObject *(*ConstructObjectFunction)();
 108
 109 public:
 110         CGUI();
 111         ~CGUI();
 112
 113         /**
 114          * Initializes GUI script classes
 115          */
 116         static void ScriptingInit();
 117
 118         /**
 119          * Initializes the GUI, needs to be called before the GUI is used
 120          */
 121         void Initialize();
 122
 123         /**
 124          * Performs processing that should happen every frame
 125          * (including sending the "Tick" event to scripts)
 126          */
 127         void TickObjects();
 128
 129         /**
 130          * Sends a specified script event to every object
 131          *
 132          * @param EventName String representation of event name
 133          */
 134         void SendEventToAll(const CStr& EventName);
 135
 136         /**
 137          * Displays the whole GUI
 138          */
 139         void Draw();
 140
 141         /**
 142          * Draw GUI Sprite
 143          *
 144          * @param Sprite Object referring to the sprite (which also caches
 145          *        calculations for faster rendering)
 146          * @param CellID Number of the icon cell to use. (Ignored if this sprite doesn't
 147          *        have any images with "cell-size")
 148          * @param Z Drawing order, depth value
 149          * @param Rect Position and Size
 150          * @param Clipping The sprite shouldn't be drawn outside this rectangle
 151          */
 152         void DrawSprite(const CGUISpriteInstance& Sprite, int CellID, const float &Z,
 153                                         const CRect &Rect, const CRect &Clipping=CRect());
 154
 155         /**
 156          * Draw a SGUIText object
 157          *
 158          * @param Text Text object.
 159          * @param DefaultColor Color used if no tag applied.
 160          * @param pos position
 161          * @param z z value.
 162          * @param clipping
 163          */
 164         void DrawText(SGUIText &Text, const CColor &DefaultColor,
 165                                   const CPos &pos, const float &z, const CRect &clipping);
 166
 167         /**
 168          * Clean up, call this to clean up all memory allocated
 169          * within the GUI.
 170          */
 171         void Destroy();
 172
 173         /**
 174          * The replacement of Process(), handles an SDL_Event_
 175          *
 176          * @param ev SDL Event, like mouse/keyboard input
 177          */
 178         InReaction HandleEvent(const SDL_Event_* ev);
 179
 180         /**
 181          * Load a GUI XML file into the GUI.
 182          *
 183          * <b>VERY IMPORTANT!</b> All \<styles\>-files must be read before
 184          * everything else!
 185          *
 186          * @param Filename Name of file
 187          * @param Paths Set of paths; all XML and JS files loaded will be added to this
 188          */
 189         void LoadXmlFile(const VfsPath& Filename, boost::unordered_set<VfsPath>& Paths);
 190
 191         /**
 192          * Checks if object exists and return true or false accordingly
 193          *
 194          * @param Name String name of object
 195          * @return true if object exists
 196          */
 197         bool ObjectExists(const CStr& Name) const;
 198
 199
 200         /**
 201          * Returns the GUI object with the desired name, or NULL
 202          * if no match is found,
 203          *
 204          * @param Name String name of object
 205          * @return Matching object, or NULL
 206          */
 207         IGUIObject* FindObjectByName(const CStr& Name) const;
 208
 209         /**
 210          * Returns the GUI object under the mouse, or NULL if none.
 211          */
 212         IGUIObject* FindObjectUnderMouse() const;
 213
 214         /**
 215          * The GUI needs to have all object types inputted and
 216          * their constructors. Also it needs to associate a type
 217          * by a string name of the type.
 218          *
 219          * To add a type:
 220          * @code
 221          * AddObjectType("button", &CButton::ConstructObject);
 222          * @endcode
 223          *
 224          * @param str Reference name of object type
 225          * @param pFunc Pointer of function ConstuctObject() in the object
 226          *
 227          * @see CGUI#ConstructObject()
 228          */
 229         void AddObjectType(const CStr& str, ConstructObjectFunction pFunc) { m_ObjectTypes[str] = pFunc; }
 230
 231         /**
 232          * Update Resolution, should be called every time the resolution
 233          * of the OpenGL screen has been changed, this is because it needs
 234          * to re-cache all its actual sizes
 235          *
 236          * Needs no input since screen resolution is global.
 237          *
 238          * @see IGUIObject#UpdateCachedSize()
 239          */
 240         void UpdateResolution();
 241
 242         /**
 243          * Generate a SGUIText object from the inputted string.
 244          * The function will break down the string and its
 245          * tags to calculate exactly which rendering queries
 246          * will be sent to the Renderer. Also, horizontal alignment
 247          * is taken into acount in this method but NOT vertical alignment.
 248          *
 249          * Done through the CGUI since it can communicate with
 250          *
 251          * @param Text Text to generate SGUIText object from
 252          * @param Font Default font, notice both Default color and default font
 253          *                can be changed by tags.
 254          * @param Width Width, 0 if no word-wrapping.
 255          * @param BufferZone space between text and edge, and space between text and images.
 256          * @param pObject Optional parameter for error output. Used *only* if error parsing fails,
 257          *                and we need to be able to output which object the error occured in to aid the user.
 258          */
 259         SGUIText GenerateText(const CGUIString &Text, const CStrW& Font,
 260                                                   const float &Width, const float &BufferZone,
 261                                                   const IGUIObject *pObject=NULL);
 262
 263         /**
 264          * Returns the JSObject* associated with the GUI
 265          *
 266          * @return The relevant JS object
 267          */
 268         JSObject* GetScriptObject() { return m_ScriptObject; }
 269
 270         /**
 271          * Check if an icon exists
 272          */
 273         bool IconExists(const CStr& str) const { return (m_Icons.count(str) != 0); }
 274
 275         /**
 276          * Get Icon (a copy, can never be changed)
 277          */
 278         SGUIIcon GetIcon(const CStr& str) const { return m_Icons.find(str)->second; }
 279
 280         /**
 281          * Get pre-defined color (if it exists)
 282          * Returns false if it fails.
 283          */
 284         bool GetPreDefinedColor(const CStr& name, CColor &Output);
 285
 286 private:
 287
 288         /**
 289          * Updates the object pointers, needs to be called each
 290          * time an object has been added or removed.
 291          *
 292          * This function is atomic, meaning if it throws anything, it will
 293          * have seen it through that nothing was ultimately changed.
 294          *
 295          * @throws PSERROR_GUI that is thrown from IGUIObject::AddToPointersMap().
 296          */
 297         void UpdateObjects();
 298
 299         /**
 300          * Adds an object to the GUI's object database
 301          * Private, since you can only add objects through
 302          * XML files. Why? Because it enables the GUI to
 303          * be much more encapsulated and safe.
 304          *
 305          * @throws      Rethrows PSERROR_GUI from IGUIObject::AddChild().
 306          */
 307         void AddObject(IGUIObject* pObject);
 308
 309         /**
 310          * You input the name of the object type, and let's
 311          * say you input "button", then it will construct a
 312          * CGUIObjet* as a CButton.
 313          *
 314          * @param str Name of object type
 315          * @return Newly constructed IGUIObject (but constructed as a subclass)
 316          */
 317         IGUIObject *ConstructObject(const CStr& str);
 318
 319         /**
 320          * Get Focused Object.
 321          */
 322         IGUIObject *GetFocusedObject() { return m_FocusedObject; }
 323
 324 public:
 325         /**
 326          * Change focus to new object.
 327          * Will send LOST_FOCUS/GOT_FOCUS messages as appropriate.
 328          * pObject can be NULL to remove all focus.
 329          */
 330         void SetFocusedObject(IGUIObject* pObject);
 331
 332 private:
 333         //--------------------------------------------------------
 334         /** @name XML Reading Xeromyces specific subroutines
 335          *
 336          * These does not throw!
 337          * Because when reading in XML files, it won't be fatal
 338          * if an error occurs, perhaps one particular object
 339          * fails, but it'll still continue reading in the next.
 340          * All Error are reported with ReportParseError
 341          */
 342         //--------------------------------------------------------
 343
 344         /*
 345                 Xeromyces_* functions tree
 346                 <objects> (ReadRootObjects)
 347                  |
 348                  +-<script> (ReadScript)
 349                  |
 350                  +-<object> (ReadObject)
 351                         |
 352                         +-<action>
 353                         |
 354                         +-Optional Type Extensions (IGUIObject::ReadExtendedElement) TODO
 355                         |
 356                         +-<<object>> *recursive*
 357
 358
 359                 <styles> (ReadRootStyles)
 360                  |
 361                  +-<style> (ReadStyle)
 362
 363
 364                 <sprites> (ReadRootSprites)
 365                  |
 366                  +-<sprite> (ReadSprite)
 367                         |
 368                         +-<image> (ReadImage)
 369
 370
 371                 <setup> (ReadRootSetup)
 372                  |
 373                  +-<tooltip> (ReadToolTip)
 374                  |
 375                  +-<scrollbar> (ReadScrollBar)
 376                  |
 377                  +-<icon> (ReadIcon)
 378                  |
 379                  +-<color> (ReadColor)
 380         */
 381         //@{
 382
 383         // Read Roots
 384
 385         /**
 386          * Reads in the root element \<objects\> (the DOMElement).
 387          *
 388          * @param Element       The Xeromyces object that represents
 389          *                                      the objects-tag.
 390          * @param pFile         The Xeromyces object for the file being read
 391          * @param Paths         Collects the set of all XML/JS files that are loaded
 392          *
 393          * @see LoadXmlFile()
 394          */
 395         void Xeromyces_ReadRootObjects(XMBElement Element, CXeromyces* pFile, boost::unordered_set<VfsPath>& Paths);
 396
 397         /**
 398          * Reads in the root element \<sprites\> (the DOMElement).
 399          *
 400          * @param Element       The Xeromyces object that represents
 401          *                                      the sprites-tag.
 402          * @param pFile         The Xeromyces object for the file being read
 403          *
 404          * @see LoadXmlFile()
 405          */
 406         void Xeromyces_ReadRootSprites(XMBElement Element, CXeromyces* pFile);
 407
 408         /**
 409          * Reads in the root element \<styles\> (the DOMElement).
 410          *
 411          * @param Element       The Xeromyces object that represents
 412          *                                      the styles-tag.
 413          * @param pFile         The Xeromyces object for the file being read
 414          *
 415          * @see LoadXmlFile()
 416          */
 417         void Xeromyces_ReadRootStyles(XMBElement Element, CXeromyces* pFile);
 418
 419         /**
 420          * Reads in the root element \<setup\> (the DOMElement).
 421          *
 422          * @param Element       The Xeromyces object that represents
 423          *                                      the setup-tag.
 424          * @param pFile         The Xeromyces object for the file being read
 425          *
 426          * @see LoadXmlFile()
 427          */
 428         void Xeromyces_ReadRootSetup(XMBElement Element, CXeromyces* pFile);
 429
 430         // Read Subs
 431
 432         /**
 433          * Notice! Recursive function!
 434          *
 435          * Read in an \<object\> (the XMBElement) and stores it
 436          * as a child in the pParent.
 437          *
 438          * It will also check the object's children and call this function
 439          * on them too. Also it will call all other functions that reads
 440          * in other stuff that can be found within an object. Check the
 441          * tree in the beginning of this class' Xeromyces_* section.
 442          *
 443          * @param Element       The Xeromyces object that represents
 444          *                                      the object-tag.
 445          * @param pFile         The Xeromyces object for the file being read
 446          * @param pParent       Parent to add this object as child in.
 447          * @param NameSubst     A set of substitution strings that will be
 448          *                                      applied to all object names within this object.
 449          * @param Paths         Output set of file paths that this GUI object
 450          *                                      relies on.
 451          *
 452          * @see LoadXmlFile()
 453          */
 454         void Xeromyces_ReadObject(XMBElement Element, CXeromyces* pFile, IGUIObject *pParent, const std::vector<std::pair<CStr, CStr> >& NameSubst, boost::unordered_set<VfsPath>& Paths);
 455
 456         /**
 457          * Reads in the element \<repeat\>, which repeats its child \<object\>s
 458          * 'count' times, replacing the string "[n]" in its descendants' names
 459          * with "[0]", "[1]", etc.
 460          */
 461         void Xeromyces_ReadRepeat(XMBElement Element, CXeromyces* pFile, IGUIObject *pParent, boost::unordered_set<VfsPath>& Paths);
 462
 463         /**
 464          * Reads in the element \<script\> (the XMBElement) and executes
 465          * the script's code.
 466          *
 467          * @param Element       The Xeromyces object that represents
 468          *                                      the script-tag.
 469          * @param pFile         The Xeromyces object for the file being read
 470          * @param Paths         Output set of file paths that this script is loaded from.
 471          *
 472          * @see LoadXmlFile()
 473          */
 474         void Xeromyces_ReadScript(XMBElement Element, CXeromyces* pFile, boost::unordered_set<VfsPath>& Paths);
 475
 476         /**
 477          * Reads in the element \<sprite\> (the XMBElement) and stores the
 478          * result in a new CGUISprite.
 479          *
 480          * @param Element       The Xeromyces object that represents
 481          *                                      the sprite-tag.
 482          * @param pFile         The Xeromyces object for the file being read
 483          *
 484          * @see LoadXmlFile()
 485          */
 486         void Xeromyces_ReadSprite(XMBElement Element, CXeromyces* pFile);
 487
 488         /**
 489          * Reads in the element \<image\> (the XMBElement) and stores the
 490          * result within the CGUISprite.
 491          *
 492          * @param Element       The Xeromyces object that represents
 493          *                                      the image-tag.
 494          * @param pFile         The Xeromyces object for the file being read
 495          * @param parent        Parent sprite.
 496          *
 497          * @see LoadXmlFile()
 498          */
 499         void Xeromyces_ReadImage(XMBElement Element, CXeromyces* pFile, CGUISprite &parent);
 500
 501         /**
 502          * Reads in the element \<effect\> (the XMBElement) and stores the
 503          * result within the SGUIImageEffects.
 504          *
 505          * @param Element       The Xeromyces object that represents
 506          *                                      the image-tag.
 507          * @param pFile         The Xeromyces object for the file being read
 508          * @param effects       Effects object to add this effect to.
 509          *
 510          * @see LoadXmlFile()
 511          */
 512         void Xeromyces_ReadEffects(XMBElement Element, CXeromyces* pFile, SGUIImageEffects &effects);
 513
 514         /**
 515          * Reads in the element \<style\> (the XMBElement) and stores the
 516          * result in m_Styles.
 517          *
 518          * @param Element       The Xeromyces object that represents
 519          *                                      the style-tag.
 520          * @param pFile         The Xeromyces object for the file being read
 521          *
 522          * @see LoadXmlFile()
 523          */
 524         void Xeromyces_ReadStyle(XMBElement Element, CXeromyces* pFile);
 525
 526         /**
 527          * Reads in the element \<scrollbar\> (the XMBElement) and stores the
 528          * result in m_ScrollBarStyles.
 529          *
 530          * @param Element       The Xeromyces object that represents
 531          *                                      the scrollbar-tag.
 532          * @param pFile         The Xeromyces object for the file being read
 533          *
 534          * @see LoadXmlFile()
 535          */
 536         void Xeromyces_ReadScrollBarStyle(XMBElement Element, CXeromyces* pFile);
 537
 538         /**
 539          * Reads in the element \<icon\> (the XMBElement) and stores the
 540          * result in m_Icons.
 541          *
 542          * @param Element       The Xeromyces object that represents
 543          *                                      the scrollbar-tag.
 544          * @param pFile         The Xeromyces object for the file being read
 545          *
 546          * @see LoadXmlFile()
 547          */
 548         void Xeromyces_ReadIcon(XMBElement Element, CXeromyces* pFile);
 549
 550         /**
 551          * Reads in the element \<tooltip\> (the XMBElement) and stores the
 552          * result as an object with the name __tooltip_#.
 553          *
 554          * @param Element       The Xeromyces object that represents
 555          *                                      the scrollbar-tag.
 556          * @param pFile         The Xeromyces object for the file being read
 557          *
 558          * @see LoadXmlFile()
 559          */
 560         void Xeromyces_ReadTooltip(XMBElement Element, CXeromyces* pFile);
 561
 562         /**
 563          * Reads in the element \<color\> (the XMBElement) and stores the
 564          * result in m_PreDefinedColors
 565          *
 566          * @param Element       The Xeromyces object that represents
 567          *                                      the scrollbar-tag.
 568          * @param pFile         The Xeromyces object for the file being read
 569          *
 570          * @see LoadXmlFile()
 571          */
 572         void Xeromyces_ReadColor(XMBElement Element, CXeromyces* pFile);
 573
 574         //@}
 575
 576 private:
 577
 578         // Variables
 579
 580         //--------------------------------------------------------
 581         /** @name Miscellaneous */
 582         //--------------------------------------------------------
 583         //@{
 584
 585         /**
 586          * An JSObject* under which all GUI JavaScript things will
 587          * be created, so that they can be garbage-collected
 588          * when the GUI shuts down.
 589          */
 590         JSObject* m_ScriptObject;
 591
 592         /**
 593          * don't want to pass this around with the
 594          * ChooseMouseOverAndClosest broadcast -
 595          * we'd need to pack this and pNearest in a struct
 596          */
 597         CPos m_MousePos;
 598
 599         /**
 600          * Indicates which buttons are pressed (bit 0 = LMB,
 601          * bit 1 = RMB, bit 2 = MMB)
 602          */
 603         unsigned int m_MouseButtons;
 604
 605         // Tooltip
 606         GUITooltip m_Tooltip;
 607
 608         /**
 609          * This is a bank of custom colors, it is simply a look up table that
 610          * will return a color object when someone inputs the name of that
 611          * color. Of course the colors have to be declared in XML, there are
 612          * no hard-coded values.
 613          */
 614         std::map<CStr, CColor>  m_PreDefinedColors;
 615
 616         //@}
 617         //--------------------------------------------------------
 618         /** @name Objects */
 619         //--------------------------------------------------------
 620         //@{
 621
 622         /**
 623          * Base Object, all its children are considered parentless
 624          * because this is not a real object per se.
 625          */
 626         IGUIObject* m_BaseObject;
 627
 628         /**
 629          * Focused object!
 630          * Say an input box that is selected. That one is focused.
 631          * There can only be one focused object.
 632          */
 633         IGUIObject* m_FocusedObject;
 634
 635         /**
 636          * Just pointers for fast name access, each object
 637          * is really constructed within its parent for easy
 638          * recursive management.
 639          * Notice m_BaseObject won't belong here since it's
 640          * not considered a real object.
 641          */
 642         map_pObjects m_pAllObjects;
 643
 644         /**
 645          * Number of object that has been given name automatically.
 646          * the name given will be '__internal(#)', the number (#)
 647          * being this variable. When an object's name has been set
 648          * as followed, the value will increment.
 649          */
 650         int m_InternalNameNumber;
 651
 652         /**
 653          * Function pointers to functions that constructs
 654          * IGUIObjects by name... For instance m_ObjectTypes["button"]
 655          * is filled with a function that will "return new CButton();"
 656          */
 657         std::map<CStr, ConstructObjectFunction> m_ObjectTypes;
 658
 659         /**
 660          * Map from hotkey names to objects that listen to the hotkey.
 661          * (This is an optimisation to avoid recursing over the whole GUI
 662          * tree every time a hotkey is pressed).
 663          * Currently this is only set at load time - dynamic changes to an
 664          * object's hotkey property will be ignored.
 665          */
 666         std::map<CStr, std::vector<IGUIObject*> > m_HotkeyObjects;
 667
 668         //--------------------------------------------------------
 669         //      Databases
 670         //--------------------------------------------------------
 671
 672         // Sprites
 673         std::map<CStr, CGUISprite> m_Sprites;
 674
 675         // Styles
 676         std::map<CStr, SGUIStyle> m_Styles;
 677
 678         // Scroll-bar styles
 679         std::map<CStr, SGUIScrollBarStyle> m_ScrollBarStyles;
 680
 681         // Icons
 682         std::map<CStr, SGUIIcon> m_Icons;
 683 };
 684
 685 #endif