guiControl.h

Public Functions

DECLARE_SCOPE(GuiAPI )

DefineEnumType(GuiHorizontalSizing )

DefineEnumType(GuiVerticalSizing )

  1
  2//-----------------------------------------------------------------------------
  3// Copyright (c) 2012 GarageGames, LLC
  4//
  5// Permission is hereby granted, free of charge, to any person obtaining a copy
  6// of this software and associated documentation files (the "Software"), to
  7// deal in the Software without restriction, including without limitation the
  8// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
  9// sell copies of the Software, and to permit persons to whom the Software is
 10// furnished to do so, subject to the following conditions:
 11//
 12// The above copyright notice and this permission notice shall be included in
 13// all copies or substantial portions of the Software.
 14//
 15// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 16// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 17// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 18// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 19// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 20// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 21// IN THE SOFTWARE.
 22//-----------------------------------------------------------------------------
 23
 24#ifndef _GUICONTROL_H_
 25#define _GUICONTROL_H_
 26
 27#ifndef _MPOINT3_H_
 28#include "math/mPoint3.h"
 29#endif
 30#ifndef _MRECT_H_
 31#include "math/mRect.h"
 32#endif
 33#ifndef _COLOR_H_
 34#include "core/color.h"
 35#endif
 36#ifndef _SIMBASE_H_
 37#include "console/simBase.h"
 38#endif
 39#ifndef _GUITYPES_H_ 
 40#include "gui/core/guiTypes.h"
 41#endif
 42#ifndef _UTIL_DELEGATE_H_
 43#include "core/util/delegate.h"
 44#endif
 45#ifndef _LANG_H_
 46#include "i18n/lang.h"
 47#endif
 48
 49class GuiCanvas;
 50class GuiEditCtrl;
 51class GuiWindowCtrl;
 52
 53
 54DECLARE_SCOPE( GuiAPI );
 55
 56
 57/// A delegate used in tool tip rendering.
 58///
 59/// @param   hoverPos    position to display the tip near
 60/// @param   cursorPos   the actual position of the cursor when the delegate is called
 61/// @param   tipText     optional alternate tip to be rendered
 62/// @return  Returns true if the tooltip was rendered.
 63///
 64/// @see GuiControl::mRenderTooltipDelegate
 65typedef Delegate<bool( const Point2I &hoverPos, const Point2I &cursorPos, const char *tipText )> RenderTooltipDelegate; 
 66
 67/// @defgroup gui_group Gui System
 68/// The GUI system in Torque provides a powerful way of creating
 69/// WYSIWYG User Interfaces for your Game or Application written
 70/// in Torque.  
 71///
 72/// The GUI Provides a range of different controls that you may use
 73/// to arrange and layout your GUI's, including Buttons, Lists, Bitmaps
 74/// Windows, Containers, and HUD elements.
 75///
 76/// The Base Control Class GuiControl provides a basis upon which to 
 77/// write GuiControl's that may be specific to your particular type
 78/// of game.  
 79
 80
 81/// @addtogroup gui_core_group Core
 82/// @section GuiControl_Intro Introduction
 83///
 84/// GuiControl is the base class for GUI controls in Torque. It provides these
 85/// basic areas of functionality:
 86///      - Inherits from SimGroup, so that controls can have children.
 87///      - Interfacing with a GuiControlProfile.
 88///      - An abstraction from the details of handling user input
 89///        and so forth, providing friendly hooks like onMouseEnter(), onMouseMove(),
 90///        and onMouseLeave(), onKeyDown(), and so forth.
 91///      - An abstraction from the details of rendering and resizing.
 92///      - Helper functions to manipulate the mouse (mouseLock and
 93///        mouseUnlock), and convert coordinates (localToGlobalCoord() and
 94///        globalToLocalCoord()).
 95///
 96/// @ref GUI has an overview of the GUI system.
 97///
 98///
 99/// @ingroup gui_group Gui System
100/// @{
101class GuiControl : public SimGroup
102{
103   public:
104   
105      typedef SimGroup Parent;
106      
107      friend class GuiWindowCtrl; // mCollapseGroupVec
108      friend class GuiCanvas;
109      friend class GuiEditCtrl;
110      friend class GuiDragAndDropControl; // drag callbacks
111      
112      /// Additional write flags for GuiControls.
113      enum
114      {
115         NoCheckParentCanSave = BIT( 31 ),   ///< Don't inherit mCanSave=false from parents.
116      };
117      
118      enum horizSizingOptions
119      {
120         horizResizeRight = 0,   ///< fixed on the left and width
121         horizResizeWidth,       ///< fixed on the left and right
122         horizResizeLeft,        ///< fixed on the right and width
123         horizResizeCenter,
124         horizResizeRelative,     ///< resize relative
125         horizResizeAspectLeft,    ///< resize relative to height delta (offset Left)
126         horizResizeAspectRight,   ///< resize relative to height delta (offset Right)
127         horizResizeAspectCenter,  ///< resize relative to height delta (Centered)
128         horizResizeWindowRelative ///< resize window relative
129      };
130      enum vertSizingOptions
131      {
132         vertResizeBottom = 0,   ///< fixed on the top and in height
133         vertResizeHeight,       ///< fixed on the top and bottom
134         vertResizeTop,          ///< fixed in height and on the bottom
135         vertResizeCenter,
136         vertResizeRelative,      ///< resize relative
137         vertResizeAspectTop,     ///< resize relative to width delta (offset Left)
138         vertResizeAspectBottom,  ///< resize relative to width delta (offset Right)
139         vertResizeAspectCenter,  ///< resize relative to width delta Centered)
140         vertResizeWindowRelative ///< resize window relative
141      };
142      
143   private:
144   
145      SimGroup               *mAddGroup;   ///< The internal name of a SimGroup child of the global GuiGroup in which to organize this gui on creation
146      RectI                   mBounds;     ///< The internal bounds of this control
147      
148   protected:
149   
150      GuiControlProfile* mProfile;         ///< The profile for this gui (data settings that are likely to be shared by multiple guis)
151      GuiControlProfile* mTooltipProfile;  ///< The profile for any tooltips
152      
153      /// @name Control State
154      /// @{   
155      
156      static bool setProfileProt( void *object, const char *index, const char *data );
157      static bool setTooltipProfileProt( void *object, const char *index, const char *data );
158      
159      S32      mTipHoverTime;
160      
161      /// Delegate called to render a tooltip for this control.
162      /// By default this will be set to defaultTooltipRender.
163      RenderTooltipDelegate mRenderTooltipDelegate;
164      
165      /// The default tooltip rendering function.
166      /// @see RenderTooltipDelegate
167      bool defaultTooltipRender( const Point2I &hoverPos, const Point2I &cursorPos, const char* tipText = NULL );
168      
169      bool    mVisible;
170      bool    mActive;
171      bool    mAwake;
172      bool    mSetFirstResponder;
173      bool    mIsContainer; ///< if true, then the GuiEditor can drag other controls into this one.
174      bool    mCanResize;
175      bool    mCanHit;
176      
177      S32     mLayer;
178      Point2I mMinExtent;
179      StringTableEntry mLangTableName;
180      LangTable *mLangTable;
181      
182      bool mNotifyChildrenResized;
183      
184      // Contains array of windows located inside GuiControl
185      typedef Vector< Vector< GuiWindowCtrl*> > CollapseGroupVec;
186      CollapseGroupVec mCollapseGroupVec;
187      
188      static bool smDesignTime; ///< static GuiControl boolean that specifies if the GUI Editor is active
189      /// @}
190      
191      /// @name Design Time Editor Access
192      /// @{
193      static GuiEditCtrl *smEditorHandle; ///< static GuiEditCtrl pointer that gives controls access to editor-NULL if editor is closed
194      /// @}
195      
196      /// @name Keyboard Input
197      /// @{
198      GuiControl *mFirstResponder;
199      static GuiControl *smPrevResponder;
200      static GuiControl *smCurResponder;
201      /// @}
202      
203      /// @name Control State
204      /// @{
205      
206      S32 mHorizSizing;      ///< Set from horizSizingOptions.
207      S32 mVertSizing;       ///< Set from vertSizingOptions.
208      
209      StringTableEntry mAcceleratorKey;
210      StringTableEntry mConsoleVariable;
211      
212      String mConsoleCommand;
213      String mAltConsoleCommand;
214      
215      String mTooltip;
216      
217      /// @}
218      
219      /// @name Console
220      /// The console variable collection of functions allows a console variable to be bound to the GUI control.
221      ///
222      /// This allows, say, an edit field to be bound to '$foo'. The value of the console
223      /// variable '$foo' would then be equal to the text inside the text field. Changing
224      /// either changes the other.
225      /// @{
226      
227      /// $ThisControl variable for callback execution.
228      static GuiControl* smThisControl;
229      
230      /// Set $ThisControl and evaluate the given script code.
231      const char* evaluate( const char* str );
232      
233      /// Sets the value of the console variable bound to this control
234      /// @param   value   String value to assign to control's console variable
235      void setVariable(const char *value);
236      
237      /// Sets the value of the console variable bound to this control
238      /// @param   value   Integer value to assign to control's console variable
239      void setIntVariable(S32 value);
240      
241      /// Sets the value of the console variable bound to this control
242      /// @param   value   Float value to assign to control's console variable
243      void setFloatVariable(F32 value);
244      
245      const char* getVariable(); ///< Returns value of control's bound variable as a string
246      S32 getIntVariable();      ///< Returns value of control's bound variable as a integer
247      F32 getFloatVariable();    ///< Returns value of control's bound variable as a float
248      
249      GFXStateBlockRef mDefaultGuiSB;
250      
251      /// @name Callbacks
252      /// @{
253      
254      DECLARE_CALLBACK( void, onAdd, () );
255      DECLARE_CALLBACK( void, onRemove, () );
256      
257      DECLARE_CALLBACK( void, onWake, () );
258      DECLARE_CALLBACK( void, onSleep, () );
259      
260      DECLARE_CALLBACK( void, onLoseFirstResponder, () );
261      DECLARE_CALLBACK( void, onGainFirstResponder, () );
262      
263      DECLARE_CALLBACK( void, onAction, () );
264      DECLARE_CALLBACK( void, onVisible, ( bool state ) );
265      DECLARE_CALLBACK( void, onActive, ( bool state ) );
266      
267      DECLARE_CALLBACK( void, onDialogPush, () );
268      DECLARE_CALLBACK( void, onDialogPop, () );
269      
270      DECLARE_CALLBACK( void, onControlDragEnter, ( GuiControl* control, const Point2I& dropPoint ) );
271      DECLARE_CALLBACK( void, onControlDragExit, ( GuiControl* control, const Point2I& dropPoint ) );
272      DECLARE_CALLBACK( void, onControlDragged, ( GuiControl* control, const Point2I& dropPoint ) );
273      DECLARE_CALLBACK( void, onControlDropped, ( GuiControl* control, const Point2I& dropPoint ) );
274            
275      /// @}
276      
277   public:
278   
279      /// Set the name of the console variable which this GuiObject is bound to
280      /// @param   variable   Variable name
281      void setConsoleVariable(const char *variable);
282      
283      /// Set the name of the console function bound to, such as a script function
284      /// a button calls when clicked.
285      /// @param   newCmd   Console function to attach to this GuiControl
286      void setConsoleCommand( const String& newCmd );
287      const char * getConsoleCommand(); ///< Returns the name of the function bound to this GuiControl
288      LangTable *getGUILangTable(void);
289      const UTF8 *getGUIString(S32 id);
290
291      inline String& getTooltip() { return mTooltip; } ///< Returns the tooltip
292      
293      /// @}
294      
295      /// @name Callbacks
296      /// @{
297      /// Executes a console command, and returns the result.
298      ///
299      /// The global console variable $ThisControl is set to the id of the calling
300      /// control. WARNING: because multiple controls may set $ThisControl, at any time,
301      /// the value of $ThisControl should be stored in a local variable by the
302      /// callback code. The use of the $ThisControl variable is not thread safe.
303      
304      /// Executes mConsoleCommand, and returns the result.
305      const char* execConsoleCallback();
306      /// Executes mAltConsoleCommand, and returns the result.
307      const char* execAltConsoleCallback();
308      /// @}
309      
310      static bool _setVisible( void *object, const char *index, const char *data ) { static_cast<GuiControl*>(object)->setVisible( dAtob( data ) ); return false; };
311      static bool _setActive( void *object, const char *index, const char *data ) { static_cast<GuiControl*>(object)->setActive( dAtob( data ) ); return false; };
312            
313      /// @name Editor
314      /// These functions are used by the GUI Editor
315      /// @{
316      
317      /// Sets the size of the GuiControl
318      /// @param   horz   Width of the control
319      /// @param   vert   Height of the control
320      void setSizing(S32 horz, S32 vert);
321      
322      ///   Overrides Parent Serialization to allow specific controls to not be saved (Dynamic Controls, etc)
323      void write(Stream &stream, U32 tabStop, U32 flags);
324      
325      /// Returns boolean as to whether any parent of this control has the 'no serialization' flag set.
326      bool getCanSaveParent();
327            
328      /// @}
329      
330      /// @name Initialization
331      /// @{
332      
333      DECLARE_CONOBJECT(GuiControl);
334      DECLARE_CATEGORY( "Gui Core" );
335      DECLARE_DESCRIPTION( "Base class for GUI controls. Can also be used as a generic container." );
336      
337      GuiControl();
338      virtual ~GuiControl();
339      virtual bool processArguments(S32 argc, ConsoleValueRef *argv);
340      
341      static void initPersistFields();
342      static void consoleInit();
343      
344      /// @}
345      
346      /// @name Accessors
347      /// @{
348      
349      inline const Point2I&   getPosition() const { return mBounds.point; } ///< Returns position of the control
350      inline const Point2I&   getExtent() const { return mBounds.extent; } ///< Returns extents of the control
351      inline const RectI     getBounds()const { return mBounds; }           ///< Returns the bounds of the control
352      inline const RectI     getGlobalBounds() ///< Returns the bounds of this object, in global coordinates 
353      {
354         RectI retRect = getBounds();
355         retRect.point = localToGlobalCoord( Point2I(0,0) );
356         
357         return retRect;
358      };
359      virtual Point2I   getMinExtent() const { return mMinExtent; } ///< Returns minimum size the control can be
360      virtual void      setMinExtent( const Point2I &newMinExtent ) { mMinExtent = newMinExtent; };
361      inline const S32        getLeft() const { return mBounds.point.x; } ///< Returns the X position of the control
362      inline const S32        getTop() const { return mBounds.point.y; } ///< Returns the Y position of the control
363      inline const S32        getWidth() const { return mBounds.extent.x; } ///< Returns the width of the control
364      inline const S32        getHeight() const { return mBounds.extent.y; } ///< Returns the height of the control
365      
366      inline const S32        getHorizSizing() const { return mHorizSizing; }
367      inline const S32        getVertSizing() const { return mVertSizing; }
368      
369      /// @}
370      
371      /// @name Flags
372      /// @{
373      
374      /// Sets the visibility of the control
375      /// @param   value   True if object should be visible
376      virtual void setVisible(bool value);
377      inline bool isVisible() const { return mVisible; } ///< Returns true if the object is visible
378      virtual bool isHidden() const { return !isVisible(); }
379      virtual void setHidden( bool state ) { setVisible( !state ); }
380      
381      void setCanHit( bool value ) { mCanHit = value; }
382      
383      /// Sets the status of this control as active and responding or inactive
384      /// @param   value   True if this is active
385      virtual void setActive(bool value);
386      bool isActive() { return mActive; } ///< Returns true if this control is active
387      
388      bool isAwake() { return mAwake; } ///< Returns true if this control is awake
389      
390      /// @}
391      
392      /// Get information about the size of a scroll line.
393      ///
394      /// @param   rowHeight   The height, in pixels, of a row
395      /// @param   columnWidth The width, in pixels, of a column
396      virtual void getScrollLineSizes(U32 *rowHeight, U32 *columnWidth);
397      
398      /// Get information about the cursor.
399      /// @param   cursor   Cursor information will be stored here
400      /// @param   showCursor Will be set to true if the cursor is visible
401      /// @param   lastGuiEvent GuiEvent containing cursor position and modifier keys (ie ctrl, shift, alt etc)
402      virtual void getCursor(GuiCursor *&cursor, bool &showCursor, const GuiEvent &lastGuiEvent);
403      
404      /// @name Children
405      /// @{
406      
407      /// Adds an object as a child of this object.
408      /// @param   obj   New child object of this control
409      void addObject(SimObject *obj);
410      
411      /// Removes a child object from this control.
412      /// @param   obj Object to remove from this control
413      void removeObject(SimObject *obj);
414      
415      GuiControl *getParent();  ///< Returns the control which owns this one.
416      GuiCanvas *getRoot();     ///< Returns the root canvas of this control.
417      
418      virtual bool acceptsAsChild( SimObject* object ) const;
419      
420      virtual void onGroupRemove();
421      
422      /// @}
423      
424      /// @name Coordinates
425      /// @{
426      
427      /// Translates local coordinates (wrt this object) into global coordinates
428      ///
429      /// @param   src   Local coordinates to translate
430      Point2I localToGlobalCoord(const Point2I &src);
431      
432      /// Returns global coordinates translated into local space
433      ///
434      /// @param   src   Global coordinates to translate
435      Point2I globalToLocalCoord(const Point2I &src);
436      /// @}
437      
438      /// @name Resizing
439      /// @{
440      
441      /// Changes the size and/or position of this control
442      /// @param   newPosition   New position of this control
443      /// @param   newExtent   New size of this control
444      virtual bool resize(const Point2I &newPosition, const Point2I &newExtent);
445      
446      /// Changes the position of this control
447      /// @param   newPosition   New position of this control
448      virtual bool setPosition( const Point2I &newPosition );
449      inline  void setPosition( const S32 x, const S32 y ) { setPosition(Point2I(x,y)); }
450      
451      /// Changes the size of this control
452      /// @param   newExtent   New size of this control
453      virtual bool setExtent( const Point2I &newExtent );
454      inline  void setExtent( const S32 width, const S32 height) { setExtent(Point2I(width, height)); }
455      
456      /// Changes the bounds of this control
457      /// @param   newBounds   New bounds of this control
458      virtual bool setBounds( const RectI &newBounds );
459      inline  void setBounds( const S32 left,  const S32 top,
460                             const S32 width, const S32 height) { setBounds(RectI(left, top, width, height)); }
461      
462      /// Changes the X position of this control
463      /// @param   newXPosition   New X Position of this control
464      virtual void setLeft( S32 newLeft );
465      
466      /// Changes the Y position of this control
467      /// @param   newYPosition   New Y Position of this control
468      virtual void setTop( S32 newTop );
469      
470      /// Changes the width of this control
471      /// @param   newWidth   New width of this control
472      virtual void setWidth( S32 newWidth );
473      
474      /// Changes the height of this control
475      /// @param   newHeight   New Height of this control
476      virtual void setHeight( S32 newHeight );
477      
478      /// Called when a child control of the object is resized
479      /// @param   child   Child object
480      virtual void childResized(GuiControl *child);
481      
482      /// Called when this objects parent is resized
483      /// @param   oldParentRect   The old rectangle of the parent object
484      /// @param   newParentRect   The new rectangle of the parent object
485      virtual void parentResized(const RectI &oldParentRect, const RectI &newParentRect);
486      /// @}
487      
488      /// @name Rendering
489      /// @{
490      
491      /// Called when this control is to render itself
492      /// @param   offset   The location this control is to begin rendering
493      /// @param   updateRect   The screen area this control has drawing access to
494      virtual void onRender(Point2I offset, const RectI &updateRect);
495      
496      /// Called when this control should render its children
497      /// @param   offset   The location this control is to begin rendering
498      /// @param   updateRect   The screen area this control has drawing access to
499      void renderChildControls(Point2I offset, const RectI &updateRect);
500      
501      /// Sets the area (local coordinates) this control wants refreshed each frame
502      /// @param   pos   UpperLeft point on rectangle of refresh area
503      /// @param   ext   Extent of update rect
504      void setUpdateRegion(Point2I pos, Point2I ext);
505      
506      /// Sets the update area of the control to encompass the whole control
507      virtual void setUpdate();
508      /// @}
509      
510      //child hierarchy calls
511      void awaken();          ///< Called when this control and its children have been wired up.
512      void sleep();           ///< Called when this control is no more.
513      void preRender();       ///< Pre-render this control and all its children.
514      
515      /// @name Events
516      ///
517      /// If you subclass these, make sure to call the Parent::'s versions.
518      ///
519      /// @{
520      
521      /// Called when this object is asked to wake up returns true if it's actually awake at the end
522      virtual bool onWake();
523      
524      /// Called when this object is asked to sleep
525      virtual void onSleep();
526      
527      /// Do special pre-render processing
528      virtual void onPreRender();
529      
530      /// Called when this object is removed
531      virtual void onRemove();
532      
533      /// Called when one of this objects children is removed
534      virtual void onChildRemoved( GuiControl *child );
535      
536      /// Called when this object is added to the scene
537      virtual bool onAdd();
538      
539      /// Called when the mProfile or mToolTipProfile is deleted
540      virtual void onDeleteNotify(SimObject *object);
541      
542      /// Called when this object has a new child
543      virtual void onChildAdded( GuiControl *child );
544      
545      /// @}
546      
547      /// @name Console
548      /// @{
549      
550      /// Returns the value of the variable bound to this object
551      virtual const char *getScriptValue();
552      
553      /// Sets the value of the variable bound to this object
554      virtual void setScriptValue(const char *value);
555      /// @}
556      
557      /// @name Input (Keyboard/Mouse)
558      /// @{
559      
560      /// This function will return true if the provided coordinates (wrt parent object) are
561      /// within the bounds of this control
562      /// @param   parentCoordPoint   Coordinates to test
563      virtual bool pointInControl(const Point2I& parentCoordPoint);
564      
565      /// Returns true if the global cursor is inside this control
566      bool cursorInControl();
567      
568      /// Returns the control which the provided point is under, with layering
569      /// @param   pt   Point to test
570      /// @param   initialLayer  Layer of gui objects to begin the search
571      virtual GuiControl* findHitControl(const Point2I &pt, S32 initialLayer = -1 );
572      
573      enum EHitTestFlags
574      {
575         HIT_FullBoxOnly            = BIT( 0 ),    ///< Hit only counts if all of a control's bounds are within the hit rectangle.
576         HIT_ParentPreventsChildHit = BIT( 1 ),    ///< A positive hit test on a parent control will prevent hit tests on children.
577         HIT_AddParentHits          = BIT( 2 ),    ///< Parent's that get hit should be added regardless of whether any of their children get hit, too.
578         HIT_NoCanHitNoRecurse      = BIT( 3 ),    ///< A hit-disabled control will not recurse into children.
579      };
580      
581      ///
582      virtual bool findHitControls( const RectI& rect, Vector< GuiControl*>& outResult, U32 flags = 0, S32 initialLayer = -1, U32 depth = 0 );
583      
584      /// Lock the mouse within the provided control
585      /// @param   lockingControl   Control to lock the mouse within
586      void mouseLock(GuiControl *lockingControl);
587      
588      /// Turn on mouse locking with last used lock control
589      void mouseLock();
590      
591      /// Unlock the mouse
592      void mouseUnlock();
593      
594      /// Returns true if the mouse is locked
595      bool isMouseLocked();
596      /// @}
597      
598      
599      /// General input handler.
600      virtual bool onInputEvent(const InputEventInfo &event);
601      
602      /// @name Mouse Events
603      /// These functions are called when the input event which is
604      /// in the name of the function occurs.
605      /// @{
606      virtual void onMouseUp(const GuiEvent &event);
607      virtual void onMouseDown(const GuiEvent &event);
608      virtual void onMouseMove(const GuiEvent &event);
609      virtual void onMouseDragged(const GuiEvent &event);
610      virtual void onMouseEnter(const GuiEvent &event);
611      virtual void onMouseLeave(const GuiEvent &event);
612      
613      virtual bool onMouseWheelUp(const GuiEvent &event);
614      virtual bool onMouseWheelDown(const GuiEvent &event);
615      
616      virtual void onRightMouseDown(const GuiEvent &event);
617      virtual void onRightMouseUp(const GuiEvent &event);
618      virtual void onRightMouseDragged(const GuiEvent &event);
619      
620      virtual void onMiddleMouseDown(const GuiEvent &event);
621      virtual void onMiddleMouseUp(const GuiEvent &event);
622      virtual void onMiddleMouseDragged(const GuiEvent &event);
623      /// @}
624      
625      /// @name Gamepad Events
626      /// These functions are called when the input event which is in the name of
627      /// the function occurs.
628      /// @{
629      virtual bool onGamepadButtonDown(const GuiEvent &event);  ///< Default behavior is call-through to onKeyDown
630      virtual bool onGamepadButtonUp(const GuiEvent &event);    ///< Default behavior is call-through to onKeyUp
631      virtual bool onGamepadAxisUp(const GuiEvent &event);
632      virtual bool onGamepadAxisDown(const GuiEvent &event);
633      virtual bool onGamepadAxisLeft(const GuiEvent &event);
634      virtual bool onGamepadAxisRight(const GuiEvent &event);
635      virtual bool onGamepadTrigger(const GuiEvent &event);
636      /// @}
637      
638      /// @name Editor Mouse Events
639      ///
640      /// These functions are called when the input event which is
641      /// in the name of the function occurs.  Conversely from normal
642      /// mouse events, these have a boolean return value that, if 
643      /// they return true, the editor will NOT act on them or be able
644      /// to respond to this particular event.
645      ///
646      /// This is particularly useful for when writing controls so that
647      /// they may become aware of the editor and allow customization
648      /// of their data or appearance as if they were actually in use.
649      /// For example, the GuiTabBookCtrl catches on mouse down to select
650      /// a tab and NOT let the editor do any instant group manipulation.
651      /// 
652      /// @{
653      
654      /// Called when a mouseDown event occurs on a control and the GUI editor is active
655      /// @param   event   the GuiEvent which caused the call to this function
656      /// @param   offset   the offset which is representative of the units x and y that the editor takes up on screen
657      virtual bool onMouseDownEditor(const GuiEvent &event, Point2I offset) { return false; };
658      
659      /// Called when a mouseUp event occurs on a control and the GUI editor is active
660      /// @param   event   the GuiEvent which caused the call to this function
661      /// @param   offset   the offset which is representative of the units x and y that the editor takes up on screen
662      virtual bool onMouseUpEditor(const GuiEvent &event, Point2I offset) { return false; };
663      
664      /// Called when a rightMouseDown event occurs on a control and the GUI editor is active
665      /// @param   event   the GuiEvent which caused the call to this function
666      /// @param   offset   the offset which is representative of the units x and y that the editor takes up on screen
667      virtual bool onRightMouseDownEditor(const GuiEvent &event, Point2I offset) { return false; };
668      
669      /// Called when a mouseDragged event occurs on a control and the GUI editor is active
670      /// @param   event   the GuiEvent which caused the call to this function
671      /// @param   offset   the offset which is representative of the units x and y that the editor takes up on screen
672      virtual bool onMouseDraggedEditor(const GuiEvent &event, Point2I offset) { return false; };
673      
674      /// @}
675      
676      /// @name Tabs
677      /// @{
678      
679      /// Find the first tab-accessible child of this control
680      virtual GuiControl* findFirstTabable();
681      
682      /// Find the last tab-accessible child of this control
683      /// @param   firstCall   Set to true to clear the global previous responder
684      virtual GuiControl* findLastTabable(bool firstCall = true);
685      
686      /// Find previous tab-accessible control with respect to the provided one
687      /// @param   curResponder   Current control
688      /// @param   firstCall   Set to true to clear the global previous responder
689      virtual GuiControl* findPrevTabable(GuiControl *curResponder, bool firstCall = true);
690      
691      /// Find next tab-accessible control with regards to the provided control.
692      ///
693      /// @param   curResponder   Current control
694      /// @param   firstCall   Set to true to clear the global current responder
695      virtual GuiControl* findNextTabable(GuiControl *curResponder, bool firstCall = true);
696      /// @}
697      
698      /// Returns true if the provided control is a child (grandchild, or great-grandchild) of this one.
699      ///
700      /// @param   child   Control to test
701      virtual bool controlIsChild(GuiControl *child);
702      
703      /// @name First Responder
704      /// A first responder is the control which reacts first, in it's responder chain, to keyboard events
705      /// The responder chain is set for each parent and so there is only one first responder amongst it's
706      /// children.
707      /// @{
708      
709      /// Sets the first responder for child controls
710      /// @param   firstResponder   First responder for this chain
711      virtual void setFirstResponder(GuiControl *firstResponder);
712      
713      /// Sets up this control to be the first in it's group to respond to an input event
714      /// @param   value   True if this should be a first responder
715      virtual void makeFirstResponder(bool value);
716      
717      /// Returns true if this control is a first responder
718      bool isFirstResponder();
719      
720      /// Sets this object to be a first responder
721      virtual void setFirstResponder();
722      
723      /// Clears the first responder for this chain
724      void clearFirstResponder();
725      
726      /// Returns the first responder for this chain
727      GuiControl *getFirstResponder() { return mFirstResponder; }
728      
729      /// Occurs when the control gains first-responder status.
730      virtual void onGainFirstResponder();
731      
732      /// Occurs when the control loses first-responder status.
733      virtual void onLoseFirstResponder();
734      /// @}
735      
736      /// @name Keyboard Events
737      /// @{
738      
739      /// Adds the accelerator key for this object to the canvas
740      void addAcceleratorKey();
741      
742      /// Adds this control's accelerator key to the accelerator map, and
743      /// recursively tells all children to do the same.
744      virtual void buildAcceleratorMap();
745      
746      /// Occurs when the accelerator key for this control is pressed
747      ///
748      /// @param   index   Index in the accelerator map of the key
749      virtual void acceleratorKeyPress(U32 index);
750      
751      /// Occurs when the accelerator key for this control is released
752      ///
753      /// @param   index   Index in the accelerator map of the key
754      virtual void acceleratorKeyRelease(U32 index);
755      
756      /// Happens when a key is depressed
757      /// @param   event   Event descriptor (which contains the key)
758      virtual bool onKeyDown(const GuiEvent &event);
759      
760      /// Happens when a key is released
761      /// @param   event   Event descriptor (which contains the key)
762      virtual bool onKeyUp(const GuiEvent &event);
763      
764      /// Happens when a key is held down, resulting in repeated keystrokes.
765      /// @param   event   Event descriptor (which contains the key)
766      virtual bool onKeyRepeat(const GuiEvent &event);
767      /// @}
768      
769      /// Return the delegate used to render tooltips on this control.
770      RenderTooltipDelegate& getRenderTooltipDelegate() { return mRenderTooltipDelegate; }
771      const RenderTooltipDelegate& getRenderTooltipDelegate() const { return mRenderTooltipDelegate; }
772      
773      /// Returns our tooltip profile (and finds the profile if it hasn't been set yet)
774      GuiControlProfile* getTooltipProfile() { return mTooltipProfile; }
775      
776      /// Sets the tooltip profile for this control.
777      ///
778      /// @see GuiControlProfile
779      /// @param   prof   Tooltip profile to apply
780      void setTooltipProfile(GuiControlProfile *prof);
781      
782      /// Returns our profile (and finds the profile if it hasn't been set yet)
783      GuiControlProfile* getControlProfile() { return mProfile; }
784      
785      /// Sets the control profile for this control.
786      ///
787      /// @see GuiControlProfile
788      /// @param   prof   Control profile to apply
789      void setControlProfile(GuiControlProfile *prof);
790      
791      /// Occurs when this control performs its "action"
792      virtual void onAction();
793      
794      /// @name Peer Messaging
795      /// Used to send a message to other GUIControls which are children of the same parent.
796      ///
797      /// This is mostly used by radio controls.
798      /// @{
799      void messageSiblings(S32 message);                      ///< Send a message to all siblings
800      virtual void onMessage(GuiControl *sender, S32 msg);    ///< Receive a message from another control
801      /// @}
802      
803      /// @name Canvas Events
804      /// Functions called by the canvas
805      /// @{
806      
807      /// Called if this object is a dialog, when it is added to the visible layers
808      virtual void onDialogPush();
809      
810      /// Called if this object is a dialog, when it is removed from the visible layers
811      virtual void onDialogPop();
812      /// @}
813      
814      /// Renders justified text using the profile.
815      ///
816      /// @note This should move into the graphics library at some point
817      void renderJustifiedText(Point2I offset, Point2I extent, const char *text);
818      
819      /// Returns text clipped to fit within a pixel width. The clipping 
820      /// occurs on the right side and "..." is appended.  It returns width
821      /// of the final clipped text in pixels.
822      U32 clipText( String &inOutText, U32 width ) const;
823      
824      void inspectPostApply();
825      void inspectPreApply();
826};
827
828typedef GuiControl::horizSizingOptions GuiHorizontalSizing;
829typedef GuiControl::vertSizingOptions GuiVerticalSizing;
830
831DefineEnumType( GuiHorizontalSizing );
832DefineEnumType( GuiVerticalSizing );
833
834/// @}
835
836#endif
837