inc/FUiCtrlOptionMenu.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Flora License, Version 1.0 (the License);
   6 // you may not use this file except in compliance with the License.
   7 // You may obtain a copy of the License at
   8 //
   9 //     http://floralicense.org/license/
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an AS IS BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16 //
  17 /**
  18  * @file        FUiCtrlOptionMenu.h
  19  * @brief       This is the header file for the %OptionMenu class.
  20  *
  21  * This header file contains the declarations of the %OptionMenu class and its helper classes.
  22  */
  23
  24 #ifndef _FUI_CTRL_OPTION_MENU_H_
  25 #define _FUI_CTRL_OPTION_MENU_H_
  26
  27 #include <FBaseTypes.h>
  28 #include <FBaseString.h>
  29 #include <FUiWindow.h>
  30 #include <FUiIActionEventListener.h>
  31
  32 namespace Tizen { namespace Ui { namespace Controls
  33 {
  34
  35 /**
  36  * @if OSPDEPREC
  37  * @class       OptionMenu
  38  * @brief       <i> [Deprecated] </i> This class defines a common behavior for an %OptionMenu control.
  39  *
  40  * @deprecated  This class is deprecated because the use of the %OptionMenu control is no longer recommended.
  41  * @since               2.0
  42  *
  43  * The %OptionMenu class defines a common behavior for an %OptionMenu control.
  44  * An %OptionMenu is used to present users with multiple options. Hierarchical menu
  45  * of depth 2 can be constructed. Option menu consists of main items and sub-items.
  46  * Unlike ContextMenu, menus cannot display bitmaps.
  47  *
  48  * If an application wants to perform tasks when a menu item is selected, it must
  49  * implement IActionEventListener and register the listener by calling %OptionMenu's
  50  * AddActionEventListener() method. It will then receive action ID associated
  51  * with the menu item.
  52  * Note that %OptionMenu cannot be used in a Popup.
  53  *
  54  * Example:
  55  *
  56  * @image html ui_controls_optionmenu.png
  57  *
  58  * This is the simple UI application which uses an %OptionMenu control.
  59  *
  60  * @code
  61  // Sample code for OptionMenuSample.h
  62  #include <FUi.h>
  63
  64 class OptionMenuSample
  65         : public Tizen::Ui::Controls::Form
  66         , public Tizen::Ui::IActionEventListener
  67 {
  68 public:
  69         bool Initialize(void) ;
  70         void ShowOptionMenu(void);
  71
  72         virtual result OnInitializing(void);
  73         virtual result OnTerminating(void);
  74
  75         // IActionEventListener
  76         virtual void OnActionPerformed(const Tizen::Ui::Control& source, int actionId);
  77
  78 private:
  79         static const int ID_OPTIONKEY = 100;
  80         static const int ID_OPTIONMENU_ITEM1  = 101;
  81         static const int ID_OPTIONMENU_ITEM2 = 102;
  82
  83         Tizen::Ui::Controls::OptionMenu* __pOptionMenu;
  84 };
  85  * @endcode
  86  *
  87  * @code
  88 // Sample code for OptionMenuSample.cpp
  89 #include "OptionMenuSample.h"
  90
  91 using namespace Tizen::Ui;
  92 using namespace Tizen::Ui::Controls;
  93
  94 bool
  95 OptionMenuSample::Initialize()
  96 {
  97         Construct(FORM_STYLE_OPTIONKEY|FORM_STYLE_NORMAL);
  98         return true;
  99 }
 100
 101 result
 102 OptionMenuSample::OnInitializing(void)
 103 {
 104         result r = E_SUCCESS;
 105
 106         // Creates an instance of OptionMenu
 107         __pOptionMenu = new OptionMenu();
 108         __pOptionMenu->Construct();
 109         __pOptionMenu->AddItem("Item1",ID_OPTIONMENU_ITEM1);
 110         __pOptionMenu->AddItem("Item2",ID_OPTIONMENU_ITEM2);
 111         SetOptionkeyActionId(ID_OPTIONKEY);
 112         AddOptionkeyActionListener(*this);
 113
 114         return r;
 115 }
 116
 117 result
 118 OptionMenuSample::OnTerminating(void)
 119 {
 120         result r = E_SUCCESS;
 121         delete __pOptionMenu;
 122         return r;
 123 }
 124
 125 void
 126 OptionMenuSample::ShowOptionMenu(void)
 127 {
 128         __pOptionMenu->SetShowState(true);
 129         __pOptionMenu->Show();
 130 }
 131
 132 // IActionEventListener implementation
 133 void
 134 OptionMenuSample::OnActionPerformed(const Control& source, int actionId)
 135 {
 136         switch (actionId)
 137         {
 138         case ID_OPTIONKEY:
 139                 {
 140                         ShowOptionMenu();
 141                 }
 142                 break;
 143         case ID_OPTIONMENU_ITEM1:
 144                 {
 145                         // ....
 146                 }
 147                 break;
 148         case ID_OPTIONMENU_ITEM2:
 149                 {
 150                         // ....
 151                 }
 152                 break;
 153         default:
 154                 break;
 155         }
 156 }
 157  * @endcode
 158  * @endif
 159  */
 160 class _OSP_EXPORT_ OptionMenu
 161         : public Tizen::Ui::Window
 162 {
 163 public:
 164         /**
 165          * @if OSPDEPREC
 166          * The object is not fully constructed after this constructor is called. For full construction, the Construct() method must be called right after calling this constructor.
 167          *
 168          * @brief       <i> [Deprecated] </i>
 169          * @deprecated  This class is deprecated because the use of the %OptionMenu control is no longer recommended.
 170          * @since                       2.0
 171          * @endif
 172          */
 173         OptionMenu(void);
 174
 175         /**
 176          * @if OSPDEPREC
 177          * This polymorphic destructor should be overridden if required. This way, the destructors of the derived classes are called when the destructor of this interface is called.
 178          *
 179          * @brief       <i> [Deprecated] </i>
 180          * @deprecated  This class is deprecated because the use of the %OptionMenu control is no longer recommended.
 181          * @since                       2.0
 182          * @endif
 183          */
 184         virtual ~OptionMenu(void);
 185
 186         /**
 187          * @if OSPDEPREC
 188          * Initializes this instance of %OptionMenu.
 189          *
 190          * @brief       <i> [Deprecated] </i>
 191          * @deprecated  This class is deprecated because the use of the %OptionMenu control is no longer recommended.
 192          * @since                       2.0
 193          *
 194          * @return              An error code
 195          * @exception   E_SUCCESS                               The method is successful.
 196          * @exception   E_SYSTEM                                This method has failed.
 197          * @endif
 198          */
 199         result Construct(void);
 200
 201         /**
 202          * @if OSPDEPREC
 203          * Adds a listener instance to receive action events from this control. @n
 204          * The added listener can listen to events on the given event dispatcher's context when they are fired.
 205          *
 206          * @brief       <i> [Deprecated] </i>
 207          * @deprecated  This class is deprecated because the use of the %OptionMenu control is no longer recommended.
 208          * @since                       2.0
 209          *
 210          * @param[in]   listener        The event listener to be added
 211          * @endif
 212          */
 213         void AddActionEventListener(Tizen::Ui::IActionEventListener& listener);
 214
 215         /**
 216          * @if OSPDEPREC
 217          * Removes the specified action event listener so that it no longer receives events from this control.
 218          *
 219          * @brief       <i> [Deprecated] </i>
 220          * @deprecated  This class is deprecated because the use of the %OptionMenu control is no longer recommended.
 221          * @since                       2.0
 222          *
 223          * @param[in]   listener        The event listener to be removed
 224          * @endif
 225          */
 226         void RemoveActionEventListener(Tizen::Ui::IActionEventListener& listener);
 227
 228         /**
 229          * @if OSPDEPREC
 230          * Appends new item to the end of %OptionMenu.
 231          *
 232          * @brief       <i> [Deprecated] </i>
 233          * @deprecated  This class is deprecated because the use of the %OptionMenu control is no longer recommended.
 234          * @since                       2.0
 235          *
 236          * @return              An error code
 237          * @param[in]   text                    The item to be appended
 238          * @param[in]   actionId                The action ID
 239          * @exception   E_SUCCESS               The method is successful.
 240          * @exception   E_SYSTEM                This method has failed.
 241          * @remarks     %OptionMenu can have a maximum of 12 main items.
 242          * @endif
 243          */
 244         result AddItem(const Tizen::Base::String& text, int actionId);
 245
 246         /**
 247          * @if OSPDEPREC
 248          * Inserts a specific item at the given index of %OptionMenu.
 249          *
 250          * @brief       <i> [Deprecated] </i>
 251          * @deprecated  This class is deprecated because the use of the %OptionMenu control is no longer recommended.
 252          * @since                       2.0
 253          *
 254          * @return              An error code
 255          * @param[in]   mainIndex               The main index
 256          * @param[in]   text                    The item to be set
 257          * @param[in]   actionId                The item ID
 258          * @exception   E_SUCCESS       The method is successful.
 259          * @exception   E_OUT_OF_RANGE  The specified @c index is less than @c 0 or greater than @c 12.
 260          * @exception   E_SYSTEM                The method has failed.
 261          * @remarks     %OptionMenu can have a maximum of 12 main items.
 262          * @endif
 263          */
 264         result InsertItemAt(int mainIndex, const Tizen::Base::String& text, int actionId);
 265
 266         /**
 267          * @if OSPDEPREC
 268          * Sets a specific item at the given index of %OptionMenu.
 269          *
 270          * @brief       <i> [Deprecated] </i>
 271          * @deprecated  This class is deprecated because the use of the %OptionMenu control is no longer recommended.
 272          * @since                       2.0
 273          *
 274          * @return              An error code
 275          * @param[in]   mainIndex               The main index
 276          * @param[in]   text                    The string of the item to be set
 277          * @param[in]   actionId                The item ID
 278          * @exception   E_SUCCESS       The method is successful.
 279          * @exception   E_OUT_OF_RANGE  The specified @c index is less than @c 0 or greater than @c 12.
 280          * @exception   E_SYSTEM            The method has failed.
 281          * @endif
 282          */
 283         result SetItemAt(int mainIndex, const Tizen::Base::String& text, int actionId);
 284
 285         /**
 286          * @if OSPDEPREC
 287          * Removes the item of the specified index from %OptionMenu.
 288          *
 289          * @brief       <i> [Deprecated] </i>
 290          * @deprecated  This class is deprecated because the use of the %OptionMenu control is no longer recommended.
 291          * @since                       2.0
 292          *
 293          * @return              An error code
 294          * @param[in]   mainIndex               The main index
 295          * @exception   E_SUCCESS               The method is successful.
 296          * @exception   E_OUT_OF_RANGE  The specified @c index is less than @c 0 or greater than @c 12.
 297          * @exception   E_SYSTEM                This method has failed.
 298          * @endif
 299          */
 300         result RemoveItemAt(int mainIndex);
 301
 302         /**
 303          * @if OSPDEPREC
 304          * Gets the number of items registered for %OptionMenu.
 305          *
 306          * @brief       <i> [Deprecated] </i>
 307          * @deprecated  This class is deprecated because the use of the %OptionMenu control is no longer recommended.
 308          * @since                       2.0
 309          *
 310          * @return              The number of items registered for %OptionMenu
 311          * @endif
 312          */
 313         int GetItemCount(void) const;
 314
 315         /**
 316          * @if OSPDEPREC
 317          * Gets the index of the item with the specified action ID.
 318          *
 319          * @brief       <i> [Deprecated] </i>
 320          * @deprecated  This class is deprecated because the use of the %OptionMenu control is no longer recommended.
 321          * @since                       2.0
 322          *
 323          * @return              The index of the item
 324          * @param[in]   actionId        The action ID of the item
 325          * @endif
 326          */
 327         int GetItemIndexFromActionId(int actionId) const;
 328
 329         /**
 330          * @if OSPDEPREC
 331          * Gets the action ID of the item at the specified index.
 332          *
 333          * @brief       <i> [Deprecated] </i>
 334          * @deprecated  This class is deprecated because the use of the %OptionMenu control is no longer recommended.
 335          * @since                       2.0
 336          *
 337          * @return                      The action ID of the item
 338          * @param[in]   mainIndex               The index of the item
 339          * @endif
 340          */
 341         int GetItemActionIdAt(int mainIndex) const;
 342
 343         /**
 344          * @if OSPDEPREC
 345          * Appends new sub-item to the end of %OptionMenu.
 346          *
 347          * @brief       <i> [Deprecated] </i>
 348          * @deprecated  This class is deprecated because the use of the %OptionMenu control is no longer recommended.
 349          * @since                       2.0
 350          *
 351          * @return              An error code
 352          * @param[in]   mainIndex               The index of the main item
 353          * @param[in]   text                    The string of item to be appended
 354          * @param[in]   actionId                The item ID
 355          * @exception   E_SUCCESS               The method is successful.
 356          * @exception   E_OUT_OF_RANGE  The specified @c index is less than @c 0 or greater than @c 12.
 357          * @exception   E_SYSTEM                This method has failed.
 358          * @remarks     %OptionMenu can have a maximum of 32 sub-items.
 359          * @endif
 360          */
 361         result AddSubItem(int mainIndex, const Tizen::Base::String& text, int actionId);
 362
 363         /**
 364          * @if OSPDEPREC
 365          * Inserts a specific sub-item at the given index of %OptionMenu.
 366          *
 367          * @brief       <i> [Deprecated] </i>
 368          * @deprecated  This class is deprecated because the use of the %OptionMenu control is no longer recommended.
 369          * @since                       2.0
 370          *
 371          * @return              An error code
 372          * @param[in]   mainIndex               The index of the main item
 373          * @param[in]   subIndex                The index of the sub-item
 374          * @param[in]   text                    The string of the item to be set
 375          * @param[in]   actionId                The action ID
 376          * @exception   E_SUCCESS               The method is successful.
 377          * @exception   E_OUT_OF_RANGE  The specified @c index is less than @c 0 or greater than @c 12.
 378          * @exception   E_SYSTEM                This method has failed.
 379          * @remarks     %OptionMenu can have a maximum of 32 sub-items.
 380          * @endif
 381          */
 382         result InsertSubItemAt(int mainIndex, int subIndex, const Tizen::Base::String& text, int actionId);
 383
 384         /**
 385          * @if OSPDEPREC
 386          * Sets a specific sub-item at the given index of %OptionMenu.
 387          *
 388          * @brief       <i> [Deprecated] </i>
 389          * @deprecated  This class is deprecated because the use of the %OptionMenu control is no longer recommended.
 390          * @since                       2.0
 391          *
 392          * @return              An error code
 393          * @param[in]   mainIndex               The index of the main item
 394          * @param[in]   subIndex                The index of the sub-item
 395          * @param[in]   text                    The string of the item to be set
 396          * @param[in]   actionId                The action ID
 397          * @exception   E_SUCCESS               The method is successful.
 398          * @exception   E_OUT_OF_RANGE  The specified @c index is less than @c 0 or greater than @c 12.
 399          * @exception   E_SYSTEM                This method has failed.
 400          * @endif
 401          */
 402         result SetSubItemAt(int mainIndex, int subIndex, const Tizen::Base::String& text, int actionId);
 403
 404         /**
 405          * @if OSPDEPREC
 406          * Removes the sub-item of the specified index from %OptionMenu.
 407          *
 408          * @brief       <i> [Deprecated] </i>
 409          * @deprecated  This class is deprecated because the use of the %OptionMenu control is no longer recommended.
 410          * @since                       2.0
 411          *
 412          * @return              An error code
 413          * @param[in]   mainIndex               The index of the main item
 414          * @param[in]   subIndex                The index of the sub-item
 415          * @exception   E_SUCCESS               The method is successful.
 416          * @exception   E_OUT_OF_RANGE  The specified @c index is less than @c 0 or greater than @c 12.
 417          * @exception   E_SYSTEM                This method has failed.
 418          * @endif
 419          */
 420         result RemoveSubItemAt(int mainIndex, int subIndex);
 421
 422         /**
 423          * @if OSPDEPREC
 424          * Gets the number of sub-items registered for %OptionMenu.
 425          *
 426          * @brief       <i> [Deprecated] </i>
 427          * @deprecated  This class is deprecated because the use of the %OptionMenu control is no longer recommended.
 428          * @since                       2.0
 429          *
 430          * @return              The number of sub-items registered for %OptionMenu
 431          * @param[in]   mainIndex               The index of the main item
 432          * @endif
 433          */
 434         int GetSubItemCount(int mainIndex) const;
 435
 436         /**
 437          * @if OSPDEPREC
 438          * Gets the index of the sub-item at the specified action ID.
 439          *
 440          * @brief       <i> [Deprecated] </i>
 441          * @deprecated  This class is deprecated because the use of the %OptionMenu control is no longer recommended.
 442          * @since                       2.0
 443          *
 444          * @return              The index of the item
 445          * @param[in]   actionId                The action ID of the item
 446          * @endif
 447          */
 448         int GetSubItemIndexFromActionId(int actionId) const;
 449
 450         /**
 451          * @if OSPDEPREC
 452          * Gets the action ID of the sub-item at the specified index.
 453          *
 454          * @brief       <i> [Deprecated] </i>
 455          * @deprecated  This class is deprecated because the use of the %OptionMenu control is no longer recommended.
 456          * @since                       2.0
 457          *
 458          * @return              The action ID of the item
 459          * @param[in]   mainIndex               The index of the main item
 460          * @param[in]   subIndex                The index of the sub-item
 461          * @endif
 462          */
 463         int GetSubItemActionIdAt(int mainIndex, int subIndex) const;
 464
 465 private:
 466         //
 467         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 468         //
 469         OptionMenu(const OptionMenu&);
 470
 471         //
 472         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 473         //
 474         OptionMenu& operator =(const OptionMenu&);
 475
 476         friend class _OptionMenuImpl;
 477 }; // OptionMenu
 478
 479 }}} // Tizen::Ui::Controls
 480
 481 #endif // _FUI_CTRL_OPTION_MENU_H_