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