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