guiGameListOptionsCtrl.h

Engine/source/gui/controls/guiGameListOptionsCtrl.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 _GuiGameListOptionsCtrl_H_
 25#define _GuiGameListOptionsCtrl_H_
 26
 27#include "gui/controls/guiGameListMenuCtrl.h"
 28
 29/// \class GuiGameListOptionsCtrl
 30/// A control for showing pages of options that are gamepad friendly.
 31class GuiGameListOptionsCtrl : public GuiGameListMenuCtrl
 32{
 33   typedef GuiGameListMenuCtrl Parent;
 34
 35protected:
 36   /// \struct Row
 37   /// An extension to the parent's row, adding the ability to keep a collection
 38   /// of options and track status related to them.
 39   struct Row : public Parent::Row
 40   {
 41      Vector<StringTableEntry>   mOptions;         ///< Collection of options available to display
 42      S32                        mSelectedOption;  ///< Index into mOptions pointing at the selected option
 43      bool                       mWrapOptions;     ///< Determines if options should "wrap around" at the ends
 44
 45      enum Mode
 46      {
 47         Default = 0,
 48         OptionsList,
 49         Keybind
 50      };
 51
 52      Mode mMode;
 53
 54      Row() : mSelectedOption(0), mWrapOptions(false), mMode(Mode::Default)
 55      {
 56         VECTOR_SET_ASSOCIATION( mOptions );
 57      }
 58   };
 59
 60public:
 61   /// Gets the text for the currently selected option of the given row.
 62   ///
 63   /// \param rowIndex Index of the row to get the option from.
 64   /// \return A string representing the text currently displayed as the selected
 65   /// option on the given row. If there is no such displayed text then the empty
 66   /// string is returned.
 67   StringTableEntry getCurrentOption(S32 rowIndex) const;
 68
 69   /// Attempts to set the given row to the specified selected option. The option
 70   /// will only be set if the option exists in the control.
 71   ///
 72   /// \param rowIndex Index of the row to set an option on.
 73   /// \param option The option to be made active.
 74   /// \return True if the row contained the option and was set, false otherwise.
 75   bool selectOption(S32 rowIndex, StringTableEntry option);
 76
 77   /// Sets the list of options on the given row.
 78   ///
 79   /// \param rowIndex Index of the row to set options on.
 80   /// \param optionsList A tab separated list of options for the control.
 81   void setOptions(S32 rowIndex, const char * optionsList);
 82
 83   /// Adds a row to the control.
 84   ///
 85   /// \param label The text to display on the row as a label.
 86   /// \param optionsList A tab separated list of options for the control.
 87   /// \param wrapOptions Specify true to allow options to wrap at the ends or
 88   /// false to prevent wrapping.
 89   /// \param callback [optional] Name of a script function to use as a callback
 90   /// when this row is activated. Default NULL means no callback.
 91   /// \param icon [optional] Index of the icon to use as a marker. Default -1
 92   /// means no icon will be shown on this row.
 93   /// \param yPad [optional] An extra amount of height padding before the row.
 94   /// \param enabled [optional] If this row is initially enabled. Default true.
 95   void addRow(const char* label, const char* optionsList, bool wrapOptions, const char* callback, S32 icon = -1, S32 yPad = 0, bool enabled = true);
 96
 97   void onRender(Point2I offset, const RectI &updateRect);
 98
 99   /// Callback when the mouse button is released.
100   ///
101   /// \param event A reference to the event that triggered the callback.
102   void onMouseUp(const GuiEvent &event);
103
104   /// Callback when a key is pressed.
105   ///
106   /// \param event The event that triggered this callback.
107   bool onKeyDown(const GuiEvent &event);
108
109   /// Callback when a key is repeating.
110   ///
111   /// \param event The event that triggered this callback.
112   bool onKeyRepeat(const GuiEvent &event){ return onKeyDown(event); }
113
114   /// Callback when the gamepad axis is activated.
115   ///
116   /// \param event A reference to the event that triggered the callback.
117   virtual bool onGamepadAxisLeft(const GuiEvent &event);
118
119   /// Callback when the gamepad axis is activated.
120   ///
121   /// \param event A reference to the event that triggered the callback.
122   virtual bool onGamepadAxisRight(const GuiEvent &event);
123
124   virtual void clearRows();
125
126   GuiGameListOptionsCtrl();
127   ~GuiGameListOptionsCtrl();
128
129   DECLARE_CONOBJECT(GuiGameListOptionsCtrl);
130   DECLARE_DESCRIPTION( "A control for showing pages of options that are gamepad friendly." );
131   
132   virtual bool onAdd();
133
134   /// Initializes fields accessible through the console.
135   static void initPersistFields();
136
137   static const S32 NO_OPTION = -1; ///< Indicates there is no option
138
139protected:
140   /// Checks to make sure our control has a profile of the correct type.
141   ///
142   /// \return True if the profile is of type GuiGameListOptionsProfile or false
143   /// if the profile is of any other type.
144   bool hasValidProfile() const;
145
146   /// Enforces the validity of the fields on this control and its profile (if the
147   /// profile is valid, see: hasValidProfile).
148   void enforceConstraints();
149
150   /// Adds lines around the column divisions to the feedback already provided
151   /// in the Parent.
152   void onDebugRender(Point2I offset);
153
154private:
155   /// Performs a click on the current option row. The x position is used to
156   /// determine if the left or right arrow were clicked. If one was clicked, the
157   /// option will be changed. If neither was clicked, the option is unaffected.
158   /// This method should only be called when there is an actively selected row.
159   ///
160   /// \param row The row to perform the click on.
161   /// \param xPos The x position of the the click, relative to the control.
162   void clickOption(Row * row, S32 xPos);
163
164   /// Changes the option on the currently selected row. If there is no row
165   /// selected, this method does nothing.
166   ///
167   /// \param delta The amount to change the option selection by. Typically this
168   /// will be 1 or -1.
169   void changeOption(S32 delta);
170
171   /// Changes the option on the given row.
172   ///
173   /// \param row The row to change the option on.
174   /// \param delta The amount to change the option selection by. Typically this
175   /// will be 1 or -1.
176   void changeOption(Row * row, S32 delta);
177};
178
179/// \class GuiGameListOptionsProfile
180/// A gui profile with additional fields specific to GuiGameListOptionsCtrl.
181class GuiGameListOptionsProfile : public GuiGameListMenuProfile
182{
183   typedef GuiGameListMenuProfile Parent;
184
185public:
186   /// Enforces range constraints on all required fields.
187   void enforceConstraints();
188
189   GuiGameListOptionsProfile();
190
191   S32   mColumnSplit;  ///< Absolute position of the split between columns
192   S32   mRightPad;     ///< Extra padding between the right arrow and the hit area
193
194   DECLARE_CONOBJECT(GuiGameListOptionsProfile);
195
196   /// Initializes fields accessible through the console.
197   static void initPersistFields();
198};
199
200#endif
201