guiGameListMenuCtrl.h

Engine/source/gui/controls/guiGameListMenuCtrl.h

More...

Classes:

Detailed Description

  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 _GuiGameListMenuCtrl_H_
 25#define _GuiGameListMenuCtrl_H_
 26
 27#include "gui/core/guiControl.h"
 28
 29class GuiGameListMenuProfile;
 30
 31/// \class GuiGameListMenuCtrl
 32/// A base class for cross platform menu controls that are gamepad friendly.
 33class GuiGameListMenuCtrl : public GuiControl
 34{
 35public:
 36   typedef GuiControl Parent;
 37   typedef GuiGameListMenuProfile Profile;
 38
 39protected:
 40   /// \struct Row
 41   /// Internal data representation of a single row in the control.
 42   struct Row
 43   {
 44      StringTableEntry mLabel;            ///< Text to display in the row as a label
 45      StringTableEntry mScriptCallback;   ///< Script callback when row is activated
 46      S32 mIconIndex;                     ///< Index of the icon to display on the row (-1 = no icon)
 47      S32 mHeightPad;                     ///< Extra amount to pad above this row
 48      bool mUseHighlightIcon;             ///< Toggle the use of the highlight icon
 49      bool mEnabled;                      ///< If this row is enabled or not (grayed out)
 50
 51      virtual ~Row() {}
 52   };
 53
 54public:
 55   /// \return The index of the highlighted row or NO_ROW if none of the rows
 56   /// are currently highlighted.
 57   virtual S32 getHighlighted() const { return mHighlighted; }
 58
 59   /// \return The index of the selected row or NO_ROW if none of the rows are
 60   /// currently selected.
 61   virtual S32 getSelected() const { return mSelected; }
 62
 63   /// Sets the selected row. Only rows that are enabled can be selected. Input is
 64   /// clamped to [0, mRows.size())
 65   ///
 66   /// \param index The index to set as selected.
 67   virtual void setSelected(S32 index);
 68
 69   /// Determines if the specified row is enabled or disabled.
 70   ///
 71   /// \param index Index of the row to check.
 72   /// \return True if the specified row is enabled. False if the row is not
 73   /// enabled or the given index was not valid.
 74   virtual bool isRowEnabled(S32 index) const;
 75
 76   /// Sets a row's enabled status according to the given parameters.
 77   ///
 78   /// \param index The row to set the enabled status of.
 79   /// \param enabled Indicate true to enable the row or false to disable it.
 80   virtual void setRowEnabled(S32 index, bool enabled);
 81
 82   /// Gets the label displayed on the specified row.
 83   ///
 84   /// \param rowIndex Index of the row to get the label of.
 85   /// \return The label for the row.
 86   virtual StringTableEntry getRowLabel(S32 rowIndex) const;
 87
 88   /// Sets the label on the given row.
 89   ///
 90   /// \param rowIndex Index of the row to set the label on.
 91   /// \param label Text to set as the label of the row.
 92   virtual void setRowLabel(S32 rowIndex, const char * label);
 93
 94   /// Adds a row to the control.
 95   ///
 96   /// \param label The text to display on the row as a label.
 97   /// \param callback Name of a script function to use as a callback when this
 98   /// row is activated.
 99   /// \param icon [optional] Index of the icon to use as a marker. Default -1
100   /// means no icon will be shown on this row.
101   /// \param yPad [optional] An extra amount of height padding before the row.
102   /// \param enabled [optional] If this row is initially enabled. Default true.
103   virtual void addRow(const char* label, const char* callback, S32 icon = -1, S32 yPad = 0, bool useHighlightIcon = true, bool enabled = true);
104
105   /// Activates the current row. The script callback of  the current row will
106   /// be called (if it has one).
107   virtual void activateRow();
108
109   /// Gets the number of rows in the control.
110   ///
111   /// \return The number of rows in this control.
112   virtual S32 getRowCount() const { return mRows.size(); }
113
114   GuiGameListMenuCtrl();
115   ~GuiGameListMenuCtrl();
116
117   void onRender(Point2I offset, const RectI &updateRect);
118
119   /// Callback when the object is registered with the sim.
120   ///
121   /// \return True if the profile was successfully added, false otherwise.
122   bool onAdd();
123
124   /// Callback when the control wakes up.
125   bool onWake();
126
127   /// Callback when a key is pressed.
128   ///
129   /// \param event The event that triggered this callback.
130   bool onKeyDown(const GuiEvent &event);
131
132   /// Callback when a key is repeating.
133   ///
134   /// \param event The event that triggered this callback.
135   bool onKeyRepeat(const GuiEvent &event){ return onKeyDown(event); }
136
137   /// Callback when the mouse button is clicked on the control.
138   ///
139   /// \param event A reference to the event that triggered the callback.
140   void onMouseDown(const GuiEvent &event);
141
142   /// Callback when the mouse is dragged on the control.
143   ///
144   /// \param event A reference to the event that triggered the callback.
145   void onMouseDragged(const GuiEvent &event){ onMouseDown(event); }
146
147   /// Callback when the mouse leaves the control.
148   ///
149   /// \param event A reference to the event that triggered the callback.
150   void onMouseLeave(const GuiEvent &event);
151
152   /// Callback when the mouse is moving over this control
153   ///
154   /// \param event A reference to the event that triggered the callback.
155   void onMouseMove(const GuiEvent &event);
156
157   /// Callback when the mouse button is released.
158   ///
159   /// \param event A reference to the event that triggered the callback.
160   void onMouseUp(const GuiEvent &event);
161
162   /// Callback when the gamepad axis is activated.
163   ///
164   /// \param event A reference to the event that triggered the callback.
165   virtual bool onGamepadAxisUp(const GuiEvent & event);
166
167   /// Callback when the gamepad axis is activated.
168   ///
169   /// \param event A reference to the event that triggered the callback.
170   virtual bool onGamepadAxisDown(const GuiEvent & event);
171
172   DECLARE_CONOBJECT(GuiGameListMenuCtrl);
173   DECLARE_CATEGORY( "Gui Game" );
174   DECLARE_DESCRIPTION( "Base class for cross platform menu controls that are gamepad friendly." );
175
176   /// Initializes fields accessible through the console.
177   static void initPersistFields();
178
179   static const S32 NO_ROW          = -1; ///< Indicates a query result of no row found.
180   static const S32 NO_ICON         = -1; ///< Indicates a row has no extra icon available
181
182protected:
183   /// Adds a row to the control.
184   ///
185   /// \param row A reference to the row object to fill.
186   /// \param label The text to display on the row as a label.
187   /// \param callback Name of a script function to use as a callback when this
188   /// row is activated.
189   /// \param icon [optional] Index of the icon to use as a marker. Default -1
190   /// means no icon will be shown on this row.
191   /// \param yPad [optional] An extra amount of height padding before the row.
192   /// \param enabled [optional] If this row is initially enabled. Default true.
193   virtual void addRow(Row * row, const char* label, const char* callback, S32 icon, S32 yPad, bool useHighlightIcon, bool enabled);
194
195   /// Determines if the given index is a valid row index. Any index pointing at
196   /// an existing row is valid.
197   ///
198   /// \param index The index to check for validity.
199   /// \return True if the index points at a valid row, false otherwise.
200   virtual bool isValidRowIndex(S32 index) const;
201
202   /// Sets the script variable $ThisControl to reflect this control.
203   virtual void setThisControl();
204
205   /// Called to implement debug rendering which displays colored lines to
206   /// provide visual feedback on extents and hit zones.
207   virtual void onDebugRender(Point2I offset);
208
209   /// Looks up the row having a hit area at the given global point.
210   ///
211   /// \param globalPoint The point we want to check for hitting a row.
212   /// \return The index of the hit row or NO_ROW if no row was hit.
213   virtual S32 getRow(Point2I globalPoint);
214
215   /// Checks to make sure our control has a profile of the correct type.
216   ///
217   /// \return True if the profile is of type GuiGameListMenuProfile or false if
218   /// the profile is of any other type.
219   virtual bool hasValidProfile() const;
220
221   /// Enforces the validity of the fields on this control and its profile (if
222   /// the profile is valid, see: hasValidProfile).
223   virtual void enforceConstraints();
224
225   /// @name Callbacks
226   /// @{
227   DECLARE_CALLBACK( void, onChange, () );
228   /// @}
229
230   /// Evaluates some script. If the command is empty then nothing is evaluated.
231   ///
232   /// \param command The script to evaluate.
233   void doScriptCommand(StringTableEntry command);
234
235   StringTableEntry  mCallbackOnA;  ///< Script callback when the 'A' button is pressed
236   StringTableEntry  mCallbackOnB;  ///< Script callback when the 'B' button is pressed
237   StringTableEntry  mCallbackOnX;  ///< Script callback when the 'X' button is pressed
238   StringTableEntry  mCallbackOnY;  ///< Script callback when the 'Y' button is pressed
239
240   bool              mDebugRender;  ///< Determines when to show debug render lines
241   Vector<Row*>     mRows;         ///< Holds data wrappers on all the rows we have
242
243private:
244   /// Recalculates the height of this control based on the stored row height and
245   /// and padding on the rows.
246   virtual Point2I getMinExtent() const;
247
248   /// Makes sure the height will allow all rows to be displayed without being
249   /// truncated.
250   void updateHeight();
251
252   /// Sets the first enabled row as selected. If there are no enabled rows then
253   /// selected will be set to NO_ROW.
254   void selectFirstEnabledRow();
255
256   /// Changes the currently selected row.
257   ///
258   /// \param delta The amount to change the row selection by. Typically this will
259   /// be 1 or -1.
260   void changeRow(S32 delta);
261
262   S32      mSelected;     ///< index of the currently selected row
263   S32      mHighlighted;  ///< index of the currently highlighted row
264};
265
266/// \class GuiGameListMenuProfile
267/// A gui profile with additional fields specific to GuiGameListMenuCtrl.
268class GuiGameListMenuProfile : public GuiControlProfile
269{
270   typedef GuiControlProfile Parent;
271
272public:
273   /// Enforces range constraints on all required fields.
274   virtual void enforceConstraints();
275
276   /// Get the height of rows in this profile. All rows are considered to be the
277   /// same base height. Rows can have an extra amount of y padding defined when
278   /// they are added to the control.
279   ///
280   /// \return The height of rows in this profile.
281   S32 getRowHeight() { return (mRowSize.y) ? mRowSize.y : getBitmapArrayRect(TEX_NORMAL).extent.y; }
282
283   /// Get the width of rows in this profile. All rows are considered to be the
284   /// same width.
285   ///
286   /// \return The width of rows in this profile.
287   S32 getRowWidth() { return (mRowSize.x) ? mRowSize.x : getBitmapArrayRect(TEX_NORMAL).extent.x; }
288
289   /// Row scale is the ratio between the defined row size and the raw size of
290   /// the bitmap.
291   ///
292   /// \return The row scale.
293   const Point2F & getRowScale() const { return mRowScale; }
294
295   /// Gets the extent of icons for this profile. If there are no icons you will
296   /// get a point of (0, 0);
297   ///
298   /// \return The extent of icons or (0, 0) if there aren't any.
299   Point2I getIconExtent();
300
301   /// Gets the extent of arrows for this profile. If there are no arrows you
302   /// will get a point of (0, 0).
303   ///
304   /// \return The extent of icons or (0, 0) if there aren't any.
305   Point2I getArrowExtent();
306
307   /// Gets the extent of the defined hit area for this profile. If the hit area
308   /// is not defined then it defaults to the full size of a row.
309   ///
310   /// \return The extents of the defined hit area or the full size of the row.
311   Point2I getHitAreaExtent();
312
313   /// Determines if this profile has textures for the left and right arrows.
314   ///
315   /// \return True if the profile's bitmap has textures for the arrows, false
316   /// otherwise.
317   bool hasArrows(){ return (! getBitmapArrayRect(TEX_FIRST_ARROW).extent.isZero()); }
318
319   /// Callback when the object is registered with the sim.
320   ///
321   /// \return True if the profile was successfully added, false otherwise.
322   bool onAdd();
323
324   Point2I  mHitAreaUpperLeft;   ///< Offset for the upper left corner of the hit area
325   Point2I  mHitAreaLowerRight;  ///< Offset for the lower right corner of the hit area
326   Point2I  mIconOffset;         ///< Offset for a row's extra icon
327   Point2I  mRowSize;            ///< The base size of a row
328
329   GuiGameListMenuProfile();
330
331   DECLARE_CONOBJECT(GuiGameListMenuProfile);
332
333   /// Initializes fields accessible through the console.
334   static void initPersistFields();
335   
336   enum 
337   {
338      TEX_NORMAL      = 0,  ///< texture index for a normal, unselected row
339      TEX_SELECTED    = 1,  ///< texture index for a selected row
340      TEX_HIGHLIGHT   = 2,  ///< texture index for a highlighted row (moused over, not selected)
341      TEX_DISABLED    = 3,  ///< texture index for a disabled row
342      TEX_L_ARROW_OFF = 4,  ///< texture index for the left arrow of an unselected row
343      TEX_L_ARROW_ON  = 5,  ///< texture index for the left arrow of a selected row
344      TEX_R_ARROW_OFF = 6,  ///< texture index for the right arrow of an unselected row
345      TEX_R_ARROW_ON  = 7,  ///< texture index for the right arrow of a selected row
346
347      TEX_FIRST_ARROW = 4,  ///< texture index for the first arrow
348      TEX_FIRST_ICON  = 8,  ///< texture index for the first row marker icon
349   };
350
351private:
352   Point2F  mRowScale;           ///< Ratio of row size to actual bitmap size
353};
354
355#endif
356