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