//----------------------------------------------------------------------------- // Copyright (c) 2012 GarageGames, LLC // // Permission is hereby granted, free of charge, to any person obtaining a copy // of this software and associated documentation files (the "Software"), to // deal in the Software without restriction, including without limitation the // rights to use, copy, modify, merge, publish, distribute, sublicense, and/or // sell copies of the Software, and to permit persons to whom the Software is // furnished to do so, subject to the following conditions: // // The above copyright notice and this permission notice shall be included in // all copies or substantial portions of the Software. // // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING // FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS // IN THE SOFTWARE. //----------------------------------------------------------------------------- //~~~~~~~~~~~~~~~~~~~~//~~~~~~~~~~~~~~~~~~~~//~~~~~~~~~~~~~~~~~~~~//~~~~~~~~~~~~~~~~~~~~~// // Arcane-FX for MIT Licensed Open Source version of Torque 3D from GarageGames // Copyright (C) 2015 Faust Logic, Inc. //~~~~~~~~~~~~~~~~~~~~//~~~~~~~~~~~~~~~~~~~~//~~~~~~~~~~~~~~~~~~~~//~~~~~~~~~~~~~~~~~~~~~// #ifndef _GUICONTROL_H_ #define _GUICONTROL_H_ #ifndef _MPOINT3_H_ #include "math/mPoint3.h" #endif #ifndef _MRECT_H_ #include "math/mRect.h" #endif #ifndef _COLOR_H_ #include "core/color.h" #endif #ifndef _SIMBASE_H_ #include "console/simBase.h" #endif #ifndef _GUITYPES_H_ #include "gui/core/guiTypes.h" #endif #ifndef _UTIL_DELEGATE_H_ #include "core/util/delegate.h" #endif #ifndef _LANG_H_ #include "i18n/lang.h" #endif class GuiCanvas; class GuiEditCtrl; class GuiWindowCtrl; DECLARE_SCOPE( GuiAPI ); /// A delegate used in tool tip rendering. /// /// @param hoverPos position to display the tip near /// @param cursorPos the actual position of the cursor when the delegate is called /// @param tipText optional alternate tip to be rendered /// @return Returns true if the tooltip was rendered. /// /// @see GuiControl::mRenderTooltipDelegate typedef Delegate RenderTooltipDelegate; /// @defgroup gui_group Gui System /// The GUI system in Torque provides a powerful way of creating /// WYSIWYG User Interfaces for your Game or Application written /// in Torque. /// /// The GUI Provides a range of different controls that you may use /// to arrange and layout your GUI's, including Buttons, Lists, Bitmaps /// Windows, Containers, and HUD elements. /// /// The Base Control Class GuiControl provides a basis upon which to /// write GuiControl's that may be specific to your particular type /// of game. /// @addtogroup gui_core_group Core /// @section GuiControl_Intro Introduction /// /// GuiControl is the base class for GUI controls in Torque. It provides these /// basic areas of functionality: /// - Inherits from SimGroup, so that controls can have children. /// - Interfacing with a GuiControlProfile. /// - An abstraction from the details of handling user input /// and so forth, providing friendly hooks like onMouseEnter(), onMouseMove(), /// and onMouseLeave(), onKeyDown(), and so forth. /// - An abstraction from the details of rendering and resizing. /// - Helper functions to manipulate the mouse (mouseLock and /// mouseUnlock), and convert coordinates (localToGlobalCoord() and /// globalToLocalCoord()). /// /// @ref GUI has an overview of the GUI system. /// /// /// @ingroup gui_group Gui System /// @{ class GuiControl : public SimGroup { public: typedef SimGroup Parent; typedef GuiControl Children; friend class GuiWindowCtrl; // mCollapseGroupVec friend class GuiCanvas; friend class GuiEditCtrl; friend class GuiDragAndDropControl; // drag callbacks /// Additional write flags for GuiControls. enum { NoCheckParentCanSave = BIT( 31 ), ///< Don't inherit mCanSave=false from parents. }; enum horizSizingOptions { horizResizeRight = 0, ///< fixed on the left and width horizResizeWidth, ///< fixed on the left and right horizResizeLeft, ///< fixed on the right and width horizResizeCenter, horizResizeRelative, ///< resize relative horizResizeAspectLeft, ///< resize relative to height delta (offset Left) horizResizeAspectRight, ///< resize relative to height delta (offset Right) horizResizeAspectCenter, ///< resize relative to height delta (Centered) horizResizeWindowRelative ///< resize window relative }; enum vertSizingOptions { vertResizeBottom = 0, ///< fixed on the top and in height vertResizeHeight, ///< fixed on the top and bottom vertResizeTop, ///< fixed in height and on the bottom vertResizeCenter, vertResizeRelative, ///< resize relative vertResizeAspectTop, ///< resize relative to width delta (offset Left) vertResizeAspectBottom, ///< resize relative to width delta (offset Right) vertResizeAspectCenter, ///< resize relative to width delta Centered) vertResizeWindowRelative ///< resize window relative }; private: SimGroup *mAddGroup; ///< The internal name of a SimGroup child of the global GuiGroup in which to organize this gui on creation RectI mBounds; ///< The internal bounds of this control protected: GuiControlProfile* mProfile; ///< The profile for this gui (data settings that are likely to be shared by multiple guis) GuiControlProfile* mTooltipProfile; ///< The profile for any tooltips /// @name Control State /// @{ static bool setProfileProt( void *object, const char *index, const char *data ); static bool setTooltipProfileProt( void *object, const char *index, const char *data ); S32 mTipHoverTime; /// Delegate called to render a tooltip for this control. /// By default this will be set to defaultTooltipRender. RenderTooltipDelegate mRenderTooltipDelegate; /// The default tooltip rendering function. /// @see RenderTooltipDelegate bool defaultTooltipRender( const Point2I &hoverPos, const Point2I &cursorPos, const char* tipText = NULL ); bool mVisible; bool mActive; bool mAwake; bool mSetFirstResponder; bool mIsContainer; ///< if true, then the GuiEditor can drag other controls into this one. bool mCanResize; bool mCanHit; S32 mLayer; Point2I mMinExtent; StringTableEntry mLangTableName; LangTable *mLangTable; bool mNotifyChildrenResized; // Contains array of windows located inside GuiControl typedef Vector< Vector< GuiWindowCtrl *> > CollapseGroupVec; CollapseGroupVec mCollapseGroupVec; static bool smDesignTime; ///< static GuiControl boolean that specifies if the GUI Editor is active /// @} /// @name Design Time Editor Access /// @{ static GuiEditCtrl *smEditorHandle; ///< static GuiEditCtrl pointer that gives controls access to editor-NULL if editor is closed /// @} /// @name Keyboard Input /// @{ GuiControl *mFirstResponder; static GuiControl *smPrevResponder; static GuiControl *smCurResponder; /// @} /// @name Control State /// @{ S32 mHorizSizing; ///< Set from horizSizingOptions. S32 mVertSizing; ///< Set from vertSizingOptions. StringTableEntry mAcceleratorKey; StringTableEntry mConsoleVariable; String mConsoleCommand; String mAltConsoleCommand; String mTooltip; /// @} /// @name Console /// The console variable collection of functions allows a console variable to be bound to the GUI control. /// /// This allows, say, an edit field to be bound to '$foo'. The value of the console /// variable '$foo' would then be equal to the text inside the text field. Changing /// either changes the other. /// @{ /// $ThisControl variable for callback execution. static GuiControl* smThisControl; /// Set $ThisControl and evaluate the given script code. const char* evaluate( const char* str ); /// Sets the value of the console variable bound to this control /// @param value String value to assign to control's console variable void setVariable(const char *value); /// Sets the value of the console variable bound to this control /// @param value Integer value to assign to control's console variable void setIntVariable(S32 value); /// Sets the value of the console variable bound to this control /// @param value Float value to assign to control's console variable void setFloatVariable(F32 value); const char* getVariable(); ///< Returns value of control's bound variable as a string S32 getIntVariable(); ///< Returns value of control's bound variable as a integer F32 getFloatVariable(); ///< Returns value of control's bound variable as a float GFXStateBlockRef mDefaultGuiSB; /// @name Callbacks /// @{ DECLARE_CALLBACK( void, onAdd, () ); DECLARE_CALLBACK( void, onRemove, () ); DECLARE_CALLBACK( void, onWake, () ); DECLARE_CALLBACK( void, onSleep, () ); DECLARE_CALLBACK( void, onLoseFirstResponder, () ); DECLARE_CALLBACK( void, onGainFirstResponder, () ); DECLARE_CALLBACK( void, onAction, () ); DECLARE_CALLBACK( void, onVisible, ( bool state ) ); DECLARE_CALLBACK( void, onActive, ( bool state ) ); DECLARE_CALLBACK( void, onDialogPush, () ); DECLARE_CALLBACK( void, onDialogPop, () ); DECLARE_CALLBACK( void, onControlDragEnter, ( GuiControl* control, const Point2I& dropPoint ) ); DECLARE_CALLBACK( void, onControlDragExit, ( GuiControl* control, const Point2I& dropPoint ) ); DECLARE_CALLBACK( void, onControlDragged, ( GuiControl* control, const Point2I& dropPoint ) ); DECLARE_CALLBACK( void, onControlDropped, ( GuiControl* control, const Point2I& dropPoint ) ); /// @} public: /// Set the name of the console variable which this GuiObject is bound to /// @param variable Variable name void setConsoleVariable(const char *variable); /// Set the name of the console function bound to, such as a script function /// a button calls when clicked. /// @param newCmd Console function to attach to this GuiControl void setConsoleCommand( const String& newCmd ); const char * getConsoleCommand(); ///< Returns the name of the function bound to this GuiControl LangTable *getGUILangTable(void); const UTF8 *getGUIString(S32 id); inline String& getTooltip() { return mTooltip; } ///< Returns the tooltip /// @} /// @name Callbacks /// @{ /// Executes a console command, and returns the result. /// /// The global console variable $ThisControl is set to the id of the calling /// control. WARNING: because multiple controls may set $ThisControl, at any time, /// the value of $ThisControl should be stored in a local variable by the /// callback code. The use of the $ThisControl variable is not thread safe. /// Executes mConsoleCommand, and returns the result. const char* execConsoleCallback(); /// Executes mAltConsoleCommand, and returns the result. const char* execAltConsoleCallback(); /// @} static bool _setVisible( void *object, const char *index, const char *data ) { static_cast(object)->setVisible( dAtob( data ) ); return false; }; static bool _setActive( void *object, const char *index, const char *data ) { static_cast(object)->setActive( dAtob( data ) ); return false; }; /// @name Editor /// These functions are used by the GUI Editor /// @{ /// Sets the size of the GuiControl /// @param horz Width of the control /// @param vert Height of the control void setSizing(S32 horz, S32 vert); /// Overrides Parent Serialization to allow specific controls to not be saved (Dynamic Controls, etc) void write(Stream &stream, U32 tabStop, U32 flags); /// Returns boolean as to whether any parent of this control has the 'no serialization' flag set. bool getCanSaveParent(); /// @} /// @name Initialization /// @{ DECLARE_CONOBJECT(GuiControl); DECLARE_CATEGORY( "Gui Core" ); DECLARE_DESCRIPTION( "Base class for GUI controls. Can also be used as a generic container." ); GuiControl(); virtual ~GuiControl(); virtual bool processArguments(S32 argc, ConsoleValue *argv); static void initPersistFields(); static void consoleInit(); /// @} /// @name Accessors /// @{ inline const Point2I& getPosition() const { return mBounds.point; } ///< Returns position of the control inline const Point2I& getExtent() const { return mBounds.extent; } ///< Returns extents of the control inline const RectI getBounds()const { return mBounds; } ///< Returns the bounds of the control inline const RectI getGlobalBounds() ///< Returns the bounds of this object, in global coordinates { RectI retRect = getBounds(); retRect.point = localToGlobalCoord( Point2I(0,0) ); return retRect; }; virtual Point2I getMinExtent() const { return mMinExtent; } ///< Returns minimum size the control can be virtual void setMinExtent( const Point2I &newMinExtent ) { mMinExtent = newMinExtent; }; inline const S32 getLeft() const { return mBounds.point.x; } ///< Returns the X position of the control inline const S32 getTop() const { return mBounds.point.y; } ///< Returns the Y position of the control inline const S32 getWidth() const { return mBounds.extent.x; } ///< Returns the width of the control inline const S32 getHeight() const { return mBounds.extent.y; } ///< Returns the height of the control inline const S32 getHorizSizing() const { return mHorizSizing; } inline const S32 getVertSizing() const { return mVertSizing; } /// @} /// @name Flags /// @{ /// Sets the visibility of the control /// @param value True if object should be visible virtual void setVisible(bool value); inline bool isVisible() const { return mVisible; } ///< Returns true if the object is visible virtual bool isHidden() const { return !isVisible(); } virtual void setHidden( bool state ) { setVisible( !state ); } void setCanHit( bool value ) { mCanHit = value; } /// Sets the status of this control as active and responding or inactive /// @param value True if this is active virtual void setActive(bool value); bool isActive() { return mActive; } ///< Returns true if this control is active bool isAwake() { return mAwake; } ///< Returns true if this control is awake /// @} /// Get information about the size of a scroll line. /// /// @param rowHeight The height, in pixels, of a row /// @param columnWidth The width, in pixels, of a column virtual void getScrollLineSizes(U32 *rowHeight, U32 *columnWidth); /// Get information about the cursor. /// @param cursor Cursor information will be stored here /// @param showCursor Will be set to true if the cursor is visible /// @param lastGuiEvent GuiEvent containing cursor position and modifier keys (ie ctrl, shift, alt etc) virtual void getCursor(GuiCursor *&cursor, bool &showCursor, const GuiEvent &lastGuiEvent); /// @name Children /// @{ /// Adds an object as a child of this object. /// @param obj New child object of this control void addObject(SimObject *obj); /// Removes a child object from this control. /// @param obj Object to remove from this control void removeObject(SimObject *obj); GuiControl *getParent(); ///< Returns the control which owns this one. GuiCanvas *getRoot(); ///< Returns the root canvas of this control. virtual bool acceptsAsChild( SimObject* object ) const; virtual void onGroupRemove(); /// @} /// @name Coordinates /// @{ /// Translates local coordinates (wrt this object) into global coordinates /// /// @param src Local coordinates to translate Point2I localToGlobalCoord(const Point2I &src); /// Returns global coordinates translated into local space /// /// @param src Global coordinates to translate Point2I globalToLocalCoord(const Point2I &src); /// @} /// @name Resizing /// @{ /// Changes the size and/or position of this control /// @param newPosition New position of this control /// @param newExtent New size of this control virtual bool resize(const Point2I &newPosition, const Point2I &newExtent); /// Changes the position of this control /// @param newPosition New position of this control virtual bool setPosition( const Point2I &newPosition ); inline void setPosition( const S32 x, const S32 y ) { setPosition(Point2I(x,y)); } /// Changes the size of this control /// @param newExtent New size of this control virtual bool setExtent( const Point2I &newExtent ); inline void setExtent( const S32 width, const S32 height) { setExtent(Point2I(width, height)); } /// Changes the bounds of this control /// @param newBounds New bounds of this control virtual bool setBounds( const RectI &newBounds ); inline void setBounds( const S32 left, const S32 top, const S32 width, const S32 height) { setBounds(RectI(left, top, width, height)); } /// Changes the X position of this control /// @param newXPosition New X Position of this control virtual void setLeft( S32 newLeft ); /// Changes the Y position of this control /// @param newYPosition New Y Position of this control virtual void setTop( S32 newTop ); /// Changes the width of this control /// @param newWidth New width of this control virtual void setWidth( S32 newWidth ); /// Changes the height of this control /// @param newHeight New Height of this control virtual void setHeight( S32 newHeight ); /// Called when a child control of the object is resized /// @param child Child object virtual void childResized(GuiControl *child); /// Called when this objects parent is resized /// @param oldParentRect The old rectangle of the parent object /// @param newParentRect The new rectangle of the parent object virtual void parentResized(const RectI &oldParentRect, const RectI &newParentRect); /// @} /// @name Rendering /// @{ /// Called when this control is to render itself /// @param offset The location this control is to begin rendering /// @param updateRect The screen area this control has drawing access to virtual void onRender(Point2I offset, const RectI &updateRect); /// Called when this control should render its children /// @param offset The location this control is to begin rendering /// @param updateRect The screen area this control has drawing access to void renderChildControls(Point2I offset, const RectI &updateRect); /// Sets the area (local coordinates) this control wants refreshed each frame /// @param pos UpperLeft point on rectangle of refresh area /// @param ext Extent of update rect void setUpdateRegion(Point2I pos, Point2I ext); /// Sets the update area of the control to encompass the whole control virtual void setUpdate(); /// @} //child hierarchy calls void awaken(); ///< Called when this control and its children have been wired up. void sleep(); ///< Called when this control is no more. void preRender(); ///< Pre-render this control and all its children. /// @name Events /// /// If you subclass these, make sure to call the Parent::'s versions. /// /// @{ /// Called when this object is asked to wake up returns true if it's actually awake at the end virtual bool onWake(); /// Called when this object is asked to sleep virtual void onSleep(); /// Do special pre-render processing virtual void onPreRender(); /// Called when this object is removed virtual void onRemove(); /// Called when one of this objects children is removed virtual void onChildRemoved( GuiControl *child ); /// Called when this object is added to the scene virtual bool onAdd(); /// Called when the mProfile or mToolTipProfile is deleted virtual void onDeleteNotify(SimObject *object); /// Called when this object has a new child virtual void onChildAdded( GuiControl *child ); /// @} /// @name Console /// @{ /// Returns the value of the variable bound to this object virtual const char *getScriptValue(); /// Sets the value of the variable bound to this object virtual void setScriptValue(const char *value); /// @} /// @name Input (Keyboard/Mouse) /// @{ /// This function will return true if the provided coordinates (wrt parent object) are /// within the bounds of this control /// @param parentCoordPoint Coordinates to test virtual bool pointInControl(const Point2I& parentCoordPoint); /// Returns true if the global cursor is inside this control bool cursorInControl(); /// Returns the control which the provided point is under, with layering /// @param pt Point to test /// @param initialLayer Layer of gui objects to begin the search virtual GuiControl* findHitControl(const Point2I &pt, S32 initialLayer = -1 ); enum EHitTestFlags { HIT_FullBoxOnly = BIT( 0 ), ///< Hit only counts if all of a control's bounds are within the hit rectangle. HIT_ParentPreventsChildHit = BIT( 1 ), ///< A positive hit test on a parent control will prevent hit tests on children. HIT_AddParentHits = BIT( 2 ), ///< Parent's that get hit should be added regardless of whether any of their children get hit, too. HIT_NoCanHitNoRecurse = BIT( 3 ), ///< A hit-disabled control will not recurse into children. }; /// virtual bool findHitControls( const RectI& rect, Vector< GuiControl* >& outResult, U32 flags = 0, S32 initialLayer = -1, U32 depth = 0 ); /// Lock the mouse within the provided control /// @param lockingControl Control to lock the mouse within void mouseLock(GuiControl *lockingControl); /// Turn on mouse locking with last used lock control void mouseLock(); /// Unlock the mouse void mouseUnlock(); /// Returns true if the mouse is locked bool isMouseLocked(); /// @} /// General input handler. virtual bool onInputEvent(const InputEventInfo &event); /// @name Mouse Events /// These functions are called when the input event which is /// in the name of the function occurs. /// @{ virtual void onMouseUp(const GuiEvent &event); virtual void onMouseDown(const GuiEvent &event); virtual void onMouseMove(const GuiEvent &event); virtual void onMouseDragged(const GuiEvent &event); virtual void onMouseEnter(const GuiEvent &event); virtual void onMouseLeave(const GuiEvent &event); virtual bool onMouseWheelUp(const GuiEvent &event); virtual bool onMouseWheelDown(const GuiEvent &event); virtual void onRightMouseDown(const GuiEvent &event); virtual void onRightMouseUp(const GuiEvent &event); virtual void onRightMouseDragged(const GuiEvent &event); virtual void onMiddleMouseDown(const GuiEvent &event); virtual void onMiddleMouseUp(const GuiEvent &event); virtual void onMiddleMouseDragged(const GuiEvent &event); /// @} /// @name Gamepad Events /// These functions are called when the input event which is in the name of /// the function occurs. /// @{ virtual bool onGamepadButtonDown(const GuiEvent &event); ///< Default behavior is call-through to onKeyDown virtual bool onGamepadButtonUp(const GuiEvent &event); ///< Default behavior is call-through to onKeyUp virtual bool onGamepadAxisUp(const GuiEvent &event); virtual bool onGamepadAxisDown(const GuiEvent &event); virtual bool onGamepadAxisLeft(const GuiEvent &event); virtual bool onGamepadAxisRight(const GuiEvent &event); virtual bool onGamepadTrigger(const GuiEvent &event); /// @} /// @name Editor Mouse Events /// /// These functions are called when the input event which is /// in the name of the function occurs. Conversely from normal /// mouse events, these have a boolean return value that, if /// they return true, the editor will NOT act on them or be able /// to respond to this particular event. /// /// This is particularly useful for when writing controls so that /// they may become aware of the editor and allow customization /// of their data or appearance as if they were actually in use. /// For example, the GuiTabBookCtrl catches on mouse down to select /// a tab and NOT let the editor do any instant group manipulation. /// /// @{ /// Called when a mouseDown event occurs on a control and the GUI editor is active /// @param event the GuiEvent which caused the call to this function /// @param offset the offset which is representative of the units x and y that the editor takes up on screen virtual bool onMouseDownEditor(const GuiEvent &event, Point2I offset) { return false; }; /// Called when a mouseUp event occurs on a control and the GUI editor is active /// @param event the GuiEvent which caused the call to this function /// @param offset the offset which is representative of the units x and y that the editor takes up on screen virtual bool onMouseUpEditor(const GuiEvent &event, Point2I offset) { return false; }; /// Called when a rightMouseDown event occurs on a control and the GUI editor is active /// @param event the GuiEvent which caused the call to this function /// @param offset the offset which is representative of the units x and y that the editor takes up on screen virtual bool onRightMouseDownEditor(const GuiEvent &event, Point2I offset) { return false; }; /// Called when a mouseDragged event occurs on a control and the GUI editor is active /// @param event the GuiEvent which caused the call to this function /// @param offset the offset which is representative of the units x and y that the editor takes up on screen virtual bool onMouseDraggedEditor(const GuiEvent &event, Point2I offset) { return false; }; /// @} /// @name Tabs /// @{ /// Find the first tab-accessible child of this control virtual GuiControl* findFirstTabable(); /// Find the last tab-accessible child of this control /// @param firstCall Set to true to clear the global previous responder virtual GuiControl* findLastTabable(bool firstCall = true); /// Find previous tab-accessible control with respect to the provided one /// @param curResponder Current control /// @param firstCall Set to true to clear the global previous responder virtual GuiControl* findPrevTabable(GuiControl *curResponder, bool firstCall = true); /// Find next tab-accessible control with regards to the provided control. /// /// @param curResponder Current control /// @param firstCall Set to true to clear the global current responder virtual GuiControl* findNextTabable(GuiControl *curResponder, bool firstCall = true); /// @} /// Returns true if the provided control is a child (grandchild, or great-grandchild) of this one. /// /// @param child Control to test virtual bool controlIsChild(GuiControl *child); /// @name First Responder /// A first responder is the control which reacts first, in it's responder chain, to keyboard events /// The responder chain is set for each parent and so there is only one first responder amongst it's /// children. /// @{ /// Sets the first responder for child controls /// @param firstResponder First responder for this chain virtual void setFirstResponder(GuiControl *firstResponder); /// Sets up this control to be the first in it's group to respond to an input event /// @param value True if this should be a first responder virtual void makeFirstResponder(bool value); /// Returns true if this control is a first responder bool isFirstResponder(); /// Sets this object to be a first responder virtual void setFirstResponder(); /// Clears the first responder for this chain void clearFirstResponder(); /// Returns the first responder for this chain GuiControl *getFirstResponder() { return mFirstResponder; } /// Occurs when the control gains first-responder status. virtual void onGainFirstResponder(); /// Occurs when the control loses first-responder status. virtual void onLoseFirstResponder(); /// @} /// @name Keyboard Events /// @{ /// Adds the accelerator key for this object to the canvas void addAcceleratorKey(); /// Adds this control's accelerator key to the accelerator map, and /// recursively tells all children to do the same. virtual void buildAcceleratorMap(); /// Occurs when the accelerator key for this control is pressed /// /// @param index Index in the accelerator map of the key virtual void acceleratorKeyPress(U32 index); /// Occurs when the accelerator key for this control is released /// /// @param index Index in the accelerator map of the key virtual void acceleratorKeyRelease(U32 index); /// Happens when a key is depressed /// @param event Event descriptor (which contains the key) virtual bool onKeyDown(const GuiEvent &event); /// Happens when a key is released /// @param event Event descriptor (which contains the key) virtual bool onKeyUp(const GuiEvent &event); /// Happens when a key is held down, resulting in repeated keystrokes. /// @param event Event descriptor (which contains the key) virtual bool onKeyRepeat(const GuiEvent &event); /// @} /// Return the delegate used to render tooltips on this control. RenderTooltipDelegate& getRenderTooltipDelegate() { return mRenderTooltipDelegate; } const RenderTooltipDelegate& getRenderTooltipDelegate() const { return mRenderTooltipDelegate; } /// Returns our tooltip profile (and finds the profile if it hasn't been set yet) GuiControlProfile* getTooltipProfile() { return mTooltipProfile; } /// Sets the tooltip profile for this control. /// /// @see GuiControlProfile /// @param prof Tooltip profile to apply void setTooltipProfile(GuiControlProfile *prof); /// Returns our profile (and finds the profile if it hasn't been set yet) GuiControlProfile* getControlProfile() { return mProfile; } /// Sets the control profile for this control. /// /// @see GuiControlProfile /// @param prof Control profile to apply void setControlProfile(GuiControlProfile *prof); /// Occurs when this control performs its "action" virtual void onAction(); /// @name Peer Messaging /// Used to send a message to other GUIControls which are children of the same parent. /// /// This is mostly used by radio controls. /// @{ void messageSiblings(S32 message); ///< Send a message to all siblings virtual void onMessage(GuiControl *sender, S32 msg); ///< Receive a message from another control /// @} /// @name Canvas Events /// Functions called by the canvas /// @{ /// Called if this object is a dialog, when it is added to the visible layers virtual void onDialogPush(); /// Called if this object is a dialog, when it is removed from the visible layers virtual void onDialogPop(); /// @} /// Renders justified text using the profile. /// /// @note This should move into the graphics library at some point void renderJustifiedText(Point2I offset, Point2I extent, const char *text); /// Returns text clipped to fit within a pixel width. The clipping /// occurs on the right side and "..." is appended. It returns width /// of the final clipped text in pixels. U32 clipText( String &inOutText, U32 width ) const; void inspectPostApply(); void inspectPreApply(); protected: F32 fade_amt; public: void setFadeAmount(F32 amt) { fade_amt = amt; } }; typedef GuiControl::horizSizingOptions GuiHorizontalSizing; typedef GuiControl::vertSizingOptions GuiVerticalSizing; DefineEnumType( GuiHorizontalSizing ); DefineEnumType( GuiVerticalSizing ); /// @} #endif