inc/FUiCtrlContextMenu.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Apache License, Version 2.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://www.apache.org/licenses/LICENSE-2.0/
  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        FUiCtrlContextMenu.h
  20  * @brief       This is the header file for the %ContextMenu class.
  21  *
  22  * This header file contains the declarations of the %ContextMenu class and its helper classes.
  23  */
  24
  25 #ifndef _FUI_CTRL_CONTEXT_MENU_H_
  26 #define _FUI_CTRL_CONTEXT_MENU_H_
  27
  28 #include <FBaseObject.h>
  29 #include <FBaseTypes.h>
  30 #include <FBaseString.h>
  31 #include <FGrpBitmap.h>
  32 #include <FGrpRectangle.h>
  33 #include <FUiWindow.h>
  34 #include <FUiContainer.h>
  35 #include <FUiIActionEventListener.h>
  36
  37 namespace Tizen { namespace Graphics
  38 {
  39 class Bitmap;
  40 };
  41 };
  42
  43 namespace Tizen { namespace Ui { namespace Controls
  44 {
  45
  46 /**
  47  * @enum ContextMenuStyle
  48  *
  49  * Defines the %ContextMenu style.
  50  *
  51  * @since       2.0
  52  */
  53 enum ContextMenuStyle
  54 {
  55         CONTEXT_MENU_STYLE_LIST,/**< The style of the vertical list of image + text */
  56         CONTEXT_MENU_STYLE_GRID,/**< The style of the grid of buttons */
  57         CONTEXT_MENU_STYLE_ICON /**<@if OSPDEPREC @deprecated This enum value is deprecated because this style can be implemented using the CONTEXT_MENU_STYLE_GRID style @endif */
  58 } ;
  59
  60 /**
  61  * @enum ContextMenuItemStatus
  62  *
  63  * Defines the possible states of the %ContextMenu control item.
  64  *
  65  * @since 2.0
  66  */
  67 enum ContextMenuItemStatus
  68 {
  69         CONTEXT_MENU_ITEM_STATUS_NORMAL,                /**< The normal state */
  70         CONTEXT_MENU_ITEM_STATUS_PRESSED,               /**< The pressed state  */
  71         CONTEXT_MENU_ITEM_STATUS_HIGHLIGHTED    /**< The highlighted state */
  72 };
  73
  74 /**
  75  * @enum ContextMenuAnchorDirection
  76  *
  77  * Defines the direction of the %ContextMenu control.
  78  *
  79  * @since 2.0
  80  */
  81 enum ContextMenuAnchorDirection
  82 {
  83         CONTEXT_MENU_ANCHOR_DIRECTION_LEFTWARD, /**< The anchor arrow direction is leftward */
  84         CONTEXT_MENU_ANCHOR_DIRECTION_RIGHTWARD,/**< The anchor arrow direction is rightward */
  85         CONTEXT_MENU_ANCHOR_DIRECTION_UPWARD,   /**< The anchor arrow direction is upward */
  86         CONTEXT_MENU_ANCHOR_DIRECTION_DOWNWARD, /**< The anchor arrow direction is downward */
  87         CONTEXT_MENU_ANCHOR_DIRECTION_AUTO              /**< The anchor arrow direction is auto */
  88 };
  89
  90 /**
  91  * @class       ContextMenu
  92  * @brief This class defines the common behavior of a %ContextMenu control.
  93  *
  94  * @since       2.0
  95  *
  96  * The %ContextMenu class displays a special purpose window that is used to present users with context-sensitive options.
  97  *
  98  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/implementing_contextmenus.htm">ContextMenu</a>.
  99  *
 100  * The following example demonstrates how to use the %ContextMenu class.
 101  *
 102  * @code
 103 // Sample code for ContextMenuSample.h
 104 #include <FUi.h>
 105 class ContextMenuSample
 106         : public Tizen::Ui::Controls::Form
 107     , public Tizen::Ui::IActionEventListener
 108 {
 109 public:
 110         ContextMenuSample(void)
 111         :__pContextMenu(null){}
 112
 113         bool Initialize(void);
 114         void ShowContextMenu(bool show);
 115         virtual result OnInitializing(void);
 116         virtual result OnTerminating(void);
 117
 118         // IActionEventListener
 119         virtual void OnActionPerformed(const Tizen::Ui::Control& source, int actionId);
 120
 121 private:
 122         static const int ID_CONTEXTMENU_ITEM1 = 101;
 123         static const int ID_CONTEXTMENU_ITEM2 = 102;
 124         static const int ID_BTN_SHOW_CONTEXTMENU = 103;
 125
 126         Tizen::Ui::Controls::ContextMenu *__pContextMenu;
 127 };
 128
 129  *      @endcode
 130  *
 131  *      @code
 132
 133 // Sample code for ContextMenuSample.cpp
 134 #include <FGraphics.h>
 135
 136 #include "ContextMenuSample.h"
 137
 138 using namespace Tizen::Graphics;
 139 using namespace Tizen::Ui::Controls;
 140
 141 bool
 142 ContextMenuSample::Initialize(void)
 143 {
 144         Construct(FORM_STYLE_NORMAL);
 145         return true;
 146 }
 147
 148 result
 149 ContextMenuSample::OnInitializing(void)
 150 {
 151         result r = E_SUCCESS;
 152
 153         // Creates an instance of ContextMenu
 154         __pContextMenu = new ContextMenu();
 155         __pContextMenu->Construct(Point(400, 150), CONTEXT_MENU_STYLE_LIST);
 156         __pContextMenu->SetFocusable(true);
 157         __pContextMenu->AddItem(L"Item1", ID_CONTEXTMENU_ITEM1);
 158         __pContextMenu->AddItem(L"Item2", ID_CONTEXTMENU_ITEM2);
 159         __pContextMenu->AddActionEventListener(*this);
 160
 161         // Creates an instance of Button to show the context menu
 162         Button* pButton = new Button();
 163         pButton->Construct(Rectangle(50, 50, 400, 100), L"Show ContextMenu");
 164         pButton->SetActionId(ID_BTN_SHOW_CONTEXTMENU);
 165         pButton->AddActionEventListener(*this);
 166
 167         // Adds the button to the form
 168         AddControl(pButton);
 169
 170         return r;
 171 }
 172
 173 // Sets the anchor position of the context menu
 174 void
 175 ContextMenuSample::ShowContextMenu(bool show)
 176 {
 177         __pContextMenu->SetAnchorPosition(Point(300, 200));
 178
 179         // Change to desired show state
 180         __pContextMenu->SetShowState(show);
 181
 182         //Calls Show() of the control
 183         if (show)
 184         {
 185                 __pContextMenu->Show();
 186         }
 187         else
 188         {
 189                 Invalidate(true);
 190         }
 191 }
 192
 193 result
 194 ContextMenuSample::OnTerminating(void)
 195 {
 196         result r = E_SUCCESS;
 197
 198         // Deallocates the __pContextMenu
 199         __pContextMenu->Destroy();
 200
 201         return r;
 202 }
 203
 204 // IActionEventListener implementation
 205 void
 206 ContextMenuSample::OnActionPerformed(const Control& source, int actionId)
 207 {
 208         switch (actionId)
 209         {
 210         case ID_CONTEXTMENU_ITEM1:
 211                 {
 212                         // ....
 213                 }
 214                 break;
 215         case ID_CONTEXTMENU_ITEM2:
 216                 {
 217                         // ....
 218                 }
 219                 break;
 220         case ID_BTN_SHOW_CONTEXTMENU:
 221                 {
 222                         ShowContextMenu(true);
 223                 }
 224                 break;
 225         default:
 226                 break;
 227         }
 228 }
 229  * @endcode
 230  *
 231  */
 232 class _OSP_EXPORT_ ContextMenu
 233         : public Tizen::Ui::Window
 234 {
 235 public:
 236 // Lifecycle
 237         /**
 238          * The object is not fully constructed after this constructor is called. @n
 239          * For full construction, the %Construct() method must be called right after calling this constructor.
 240          *
 241          * @since       2.0
 242          *
 243          */
 244         ContextMenu(void);
 245
 246         /**
 247          * This destructor overrides Tizen::Base::Object::~Object().
 248          *
 249          * @since       2.0
 250          *
 251          */
 252         virtual ~ContextMenu(void);
 253
 254         /**
 255          * Initializes this instance of %ContextMenu with the specified parameters.
 256          *
 257          * @since               2.0
 258          *
 259          * @return              An error code
 260          * @param[in]   point           The x and y coordinates of the anchor of %ContextMenu @n
 261          *                                                              The optimal size of the control is defined in
 262          *                                                              <a href="../org.tizen.native.appprogramming/html/guide/ui/control_optimalsize.htm">Optimal Size of UI Controls</a>.
 263          * @param[in]   style                   The context menu style
 264          * @exception   E_SUCCESS               The method is successful.
 265          * @exception   E_INVALID_STATE This instance has already been constructed.
 266          * @exception   E_SYSTEM            A system error has occurred.
 267          * @remarks             The default owner will be the current Form (or Frame). It is possible that this control may not be visible
 268          * due to this ownership relationship. @n In this case, use the SetOwner() method to change the ownership to the top-most window.
 269          */
 270         result Construct(const Tizen::Graphics::Point& point, ContextMenuStyle style);
 271
 272         /**
 273          * Initializes this instance of %ContextMenu with the specified parameters.
 274          *
 275          * @since               2.1
 276          *
 277          * @return              An error code
 278          * @param[in]   point           The x and y coordinates of the anchor of %ContextMenu
 279          * @param[in]   style                   The context menu style
 280          * @exception   E_SUCCESS               The method is successful.
 281          * @exception   E_INVALID_STATE This instance has already been constructed.
 282          * @exception   E_SYSTEM            A system error has occurred.
 283          * @remarks             The default owner will be the current Form (or Frame). It is possible that this control may not be visible
 284          * due to this ownership relationship. @n In this case, use the SetOwner() method to change the ownership to the top-most window.
 285          */
 286         result Construct(const Tizen::Graphics::FloatPoint& point, ContextMenuStyle style);
 287
 288         /**
 289          * Initializes this instance of %ContextMenu with the specified parameters.
 290          *
 291          * @since               2.0
 292          *
 293          * @return              An error code
 294          * @param[in]   point                   The x and y coordinates of the anchor of the %ContextMenu control @n
 295          *                                                              The optimal size of the control is defined in
 296          *                                                              <a href="../org.tizen.native.appprogramming/html/guide/ui/control_optimalsize.htm">Optimal Size of UI Controls</a>.
 297          * @param[in]   style                   The context menu style
 298          * @param[in]   direction               The anchor arrow direction
 299          * @exception   E_SUCCESS               The method is successful.
 300          * @exception   E_INVALID_STATE This instance has already been constructed.
 301          * @exception   E_SYSTEM                A system error has occurred.
 302          * @remarks             The default owner will be the current Form (or Frame). It is possible that this control may not be visible
 303          * due to this ownership relationship. @n In this case, use the SetOwner() method to change the ownership to the top-most window.
 304          */
 305         result Construct(const Tizen::Graphics::Point& point, ContextMenuStyle style, ContextMenuAnchorDirection direction);
 306
 307         /**
 308          * Initializes this instance of %ContextMenu with the specified parameters.
 309          *
 310          * @since               2.1
 311          *
 312          * @return              An error code
 313          * @param[in]   point                   The x and y coordinates of the anchor of the %ContextMenu control @n
 314          *                                                              The optimal size of the control is defined in
 315          *                                                              <a href="../org.tizen.native.appprogramming/html/guide/ui/control_optimalsize.htm">Optimal Size of UI Controls</a>.
 316          * @param[in]   style                   The context menu style
 317          * @param[in]   direction               The anchor arrow direction
 318          * @exception   E_SUCCESS               The method is successful.
 319          * @exception   E_INVALID_STATE This instance has already been constructed.
 320          * @exception   E_SYSTEM                A system error has occurred.
 321          * @remarks             The default owner will be the current Form (or Frame). It is possible that this control may not be visible
 322          * due to this ownership relationship. @n In this case, use the SetOwner() method to change the ownership to the top-most window.
 323          */
 324         result Construct(const Tizen::Graphics::FloatPoint& point, ContextMenuStyle style, ContextMenuAnchorDirection direction);
 325
 326         /**
 327          * Adds a listener instance. @n
 328          * The added listener can listen to events on the given context of the event dispatcher when they are fired.
 329          *
 330          * @since               2.0
 331          *
 332          * @param[in]   listener        The event listener to add
 333          */
 334         void AddActionEventListener(Tizen::Ui::IActionEventListener& listener);
 335
 336         /**
 337          * Removes the specified listener instance. @n
 338          * The removed listener cannot listen to events when they are fired.
 339          *
 340          * @since               2.0
 341          *
 342          * @param[in]   listener        The event listener to remove
 343          */
 344         void RemoveActionEventListener(Tizen::Ui::IActionEventListener& listener);
 345
 346
 347 // Operation
 348         /**
 349          * Appends the specified item at the end of the %ContextMenu control. @n
 350          * The %AddItem() method can only be used when the style of the context menu is ::CONTEXT_MENU_STYLE_GRID.
 351          *
 352          * @since               2.0
 353          *
 354          * @return              An error code
 355          * @param[in]   normalBitmap            The normal bitmap of the item
 356          * @param[in]   pPressedBitmap          The pressed bitmap of the item
 357          * @param[in]   actionId                    The action ID for this item
 358          * @exception   E_SUCCESS                   The method is successful.
 359          * @exception   E_MAX_EXCEEDED      The number of items has exceeded the maximum limit.
 360          * @exception   E_SYSTEM                    A system error has occurred.
 361          */
 362         result AddItem(const Tizen::Graphics::Bitmap& normalBitmap, const Tizen::Graphics::Bitmap* pPressedBitmap, int actionId);
 363
 364          /**
 365          * Appends the specified item at the end of the %ContextMenu control. @n
 366          * The %AddItem() method can only be used when the style of the context menu is ::CONTEXT_MENU_STYLE_GRID.
 367          *
 368          * @since               2.0
 369          *
 370          * @return      An error code
 371          * @param[in]   normalBitmap        The normal bitmap of the item
 372          * @param[in]   pPressedBitmap      The pressed bitmap of the item
 373          * @param[in]   pHighlightedBitmap  The highlighted bitmap of the item
 374          * @param[in]   actionId            The action ID for this item
 375          * @exception   E_SUCCESS           The method is successful.
 376          * @exception   E_MAX_EXCEEDED      The number of items has exceeded the maximum limit.
 377          * @exception   E_SYSTEM            A system error has occurred.
 378          * @remarks     When a user navigates the user interface using the directional keys, the selected UI control is highlighted and
 379          *                      the control takes the focus.
 380          */
 381         result AddItem(const Tizen::Graphics::Bitmap& normalBitmap, const Tizen::Graphics::Bitmap* pPressedBitmap, const Tizen::Graphics::Bitmap* pHighlightedBitmap, int actionId);
 382
 383         /**
 384          * Appends the specified item at the end of the %ContextMenu control.
 385          *
 386          * @since               2.0
 387          *
 388          * @return              An error code
 389          * @param[in]   text                    The string of the item to append
 390          * @param[in]   actionId                The specified action ID for this item
 391          * @exception   E_SUCCESS               The method is successful.
 392          * @exception   E_MAX_EXCEEDED  The number of items has exceeded the maximum limit.
 393          * @exception   E_SYSTEM                A system error has occurred.
 394          */
 395         result AddItem(const Tizen::Base::String& text, int actionId);
 396
 397         /**
 398          * Appends the specified item at the end of the %ContextMenu control. @n
 399          * The %AddItem() method can only be used when the style of the context menu is ::CONTEXT_MENU_STYLE_LIST.
 400          *
 401          * @since               2.0
 402          *
 403          * @return              An error code
 404          * @param[in]   text                            The string of the item to append
 405          * @param[in]   actionId                        The specified action ID for this item
 406          * @param[in]   normalBitmap        The normal bitmap of the item
 407          * @param[in]   pPressedBitmap      The pressed bitmap of the item
 408          * @param[in]   pHighlightedBitmap  The highlighted bitmap of the item
 409          * @exception   E_SUCCESS                       The method is successful.
 410          * @exception   E_MAX_EXCEEDED          The total number of items has exceeded the maximum limit.
 411          * @exception   E_SYSTEM                        A system error has occurred.
 412          */
 413         result AddItem(const Tizen::Base::String& text, int actionId, const Tizen::Graphics::Bitmap& normalBitmap, const Tizen::Graphics::Bitmap* pPressedBitmap = null, const Tizen::Graphics::Bitmap* pHighlightedBitmap = null);
 414
 415         /**
 416          * Inserts the specified item at the given index of the %ContextMenu control. @n
 417          * The %InsertItemAt() method can only be used when the style of the context menu is ::CONTEXT_MENU_STYLE_GRID.
 418          *
 419          * @since               2.0
 420          *
 421          * @return              An error code
 422          * @param[in]   index                   The location
 423          * @param[in]   normalBitmap    The normal bitmap of the item
 424          * @param[in]   pPressedBitmap  The pressed bitmap of the item
 425          * @param[in]   actionId                The specified action ID for this item
 426          * @exception   E_SUCCESS               The method is successful.
 427          * @exception   E_MAX_EXCEEDED  The number of items has exceeded the maximum limit.
 428          * @exception   E_OUT_OF_RANGE  The specified @c index is less than @c 0 or greater than the number of items in %ContextMenu.
 429          * @exception   E_SYSTEM                A system error has occurred.
 430          * @remarks     The %ContextMenu control can have a maximum of @c 3 icons.
 431          */
 432         result InsertItemAt(int index, const Tizen::Graphics::Bitmap& normalBitmap, const Tizen::Graphics::Bitmap* pPressedBitmap, int actionId);
 433
 434          /**
 435          * Inserts the specified item at the given index of the %ContextMenu control. @n
 436          * The %InsertItemAt() method can only be used when the style of the context menu is ::CONTEXT_MENU_STYLE_GRID.
 437          *
 438          * @since               2.0
 439          *
 440          * @return              An error code
 441          * @param[in]   index                      The location
 442          * @param[in]   normalBitmap               The normal bitmap of the item
 443          * @param[in]   pPressedBitmap             The pressed bitmap of the item
 444          * @param[in]   pHighlightedBitmap         The highlighted bitmap of the item
 445          * @param[in]   actionId                   The specified action ID for this item
 446          * @exception   E_SUCCESS                  The method is successful.
 447          * @exception   E_MAX_EXCEEDED             The number of items has exceeded the maximum limit.
 448          * @exception   E_OUT_OF_RANGE             The specified @c index is less than @c 0 or greater than the number of items in %ContextMenu.
 449          * @exception   E_SYSTEM                   A system error has occurred.
 450          * @remarks     When a user navigates the user interface using the directional keys, the selected UI control is highlighted and the control takes the focus.
 451          */
 452         result InsertItemAt(int index, const Tizen::Graphics::Bitmap& normalBitmap, const Tizen::Graphics::Bitmap* pPressedBitmap, const Tizen::Graphics::Bitmap* pHighlightedBitmap, int actionId);
 453
 454         /**
 455          * Inserts the specified item at the given index of the %ContextMenu control.
 456          *
 457          * @since               2.0
 458          *
 459          * @return              An error code
 460          * @param[in]   index                   The location
 461          * @param[in]   text                    The string of the item to set
 462          * @param[in]   actionId                The specified action ID for this item
 463          * @exception   E_SUCCESS               The method is successful.
 464          * @exception   E_MAX_EXCEEDED  The number of items has exceeded the maximum limit.
 465          * @exception   E_OUT_OF_RANGE  The specified @c index is less than @c 0 or greater than the number of items in %ContextMenu.
 466          * @exception   E_SYSTEM                A system error has occurred.
 467          */
 468         result InsertItemAt(int index, const Tizen::Base::String& text, int actionId);
 469
 470         /**
 471          * Inserts the specified item at the given index of the %ContextMenu control. @n
 472          * The %InsertItemAt() method can only be used when the style of the context menu is ::CONTEXT_MENU_STYLE_LIST.
 473          *
 474          * @since               2.0
 475          *
 476          * @return              An error code
 477          * @param[in]   index                           The location
 478          * @param[in]   text                            The string of the item to set
 479          * @param[in]   actionId                        The specified action ID for this item
 480          * @param[in]   normalBitmap        The normal bitmap of the item
 481          * @param[in]   pPressedBitmap      The pressed bitmap of the item
 482          * @param[in]   pHighlightedBitmap  The highlighted bitmap of the item
 483          * @exception   E_SUCCESS                       The method is successful.
 484          * @exception   E_MAX_EXCEEDED          The number of items has exceeded the maximum limit.
 485          * @exception   E_OUT_OF_RANGE          The specified @c index is less than @c 0 or greater than the number of items in %ContextMenu.
 486          * @exception   E_SYSTEM                        A system error has occurred.
 487          */
 488         result InsertItemAt(int index, const Tizen::Base::String& text, int actionId, const Tizen::Graphics::Bitmap& normalBitmap, const Tizen::Graphics::Bitmap* pPressedBitmap = null, const Tizen::Graphics::Bitmap* pHighlightedBitmap = null);
 489
 490         /**
 491          * Sets the specified item at the given index of the %ContextMenu control. @n
 492          * The %SetItemAt() method can only be used when the style of the context menu is ::CONTEXT_MENU_STYLE_GRID.
 493          *
 494          * @since               2.0
 495          *
 496          * @return              An error code
 497          * @param[in]   index                           The location
 498          * @param[in]   normalBitmap            The normal bitmap of the item
 499          * @param[in]   pPressedBitmap          The pressed bitmap of the item
 500          * @param[in]   actionId                    The action ID for this item
 501          * @exception   E_SUCCESS                       The method is successful.
 502          * @exception   E_OUT_OF_RANGE      The specified @c index is less than @c 0 or greater than the number of items in %ContextMenu.
 503          * @exception   E_SYSTEM                        A system error has occurred.
 504          */
 505         result SetItemAt(int index, const Tizen::Graphics::Bitmap& normalBitmap, const Tizen::Graphics::Bitmap* pPressedBitmap, int actionId);
 506
 507         /**
 508          * Sets the specified item at the given index of the %ContextMenu control. @n
 509          * The %SetItemAt() method can only be used when the style of the context menu is ::CONTEXT_MENU_STYLE_GRID.
 510          *
 511          * @since           2.0
 512          *
 513          * @return        An error code
 514          * @param[in]     index                      The location
 515          * @param[in]     normalBitmap               The normal bitmap of the item
 516          * @param[in]     pPressedBitmap             The pressed bitmap of the item
 517          * @param[in]     pHighlightedBitmap         The highlighted bitmap of the item
 518          * @param[in]     actionId                   The action ID for this item
 519          * @exception     E_SUCCESS                  The method is successful.
 520          * @exception     E_OUT_OF_RANGE             The specified @c index is less than @c 0 or greater than the number of items in %ContextMenu.
 521          * @exception     E_SYSTEM                   A system error has occurred.
 522          * @remarks     When a user navigates the user interface using the directional keys, the selected UI control is highlighted and the control takes the focus.
 523          */
 524         result SetItemAt(int index, const Tizen::Graphics::Bitmap& normalBitmap, const Tizen::Graphics::Bitmap* pPressedBitmap, const Tizen::Graphics::Bitmap* pHighlightedBitmap, int actionId);
 525
 526         /**
 527          * Sets the specified item at the given index of the %ContextMenu control.
 528          *
 529          * @since               2.0
 530          *
 531          * @return              An error code
 532          * @param[in]   index                   The location
 533          * @param[in]   text                    The string of the item to set
 534          * @param[in]   actionId                The action ID for this item
 535          * @exception   E_SUCCESS               The method is successful.
 536          * @exception   E_OUT_OF_RANGE  The specified @c index less than @c 0 or greater than the number of items in %ContextMenu.
 537          * @exception   E_SYSTEM                A system error has occurred.
 538          */
 539         result SetItemAt(int index, const Tizen::Base::String& text, int actionId);
 540
 541         /**
 542          * Sets the specified item at the given index of the %ContextMenu control. @n
 543          * The %SetItemAt() method can only be used when the style of the context menu is ::CONTEXT_MENU_STYLE_LIST.
 544          *
 545          * @since               2.0
 546          *
 547          * @return              An error code
 548          * @param[in]   index                           The location
 549          * @param[in]   text                            The string of the item to set
 550          * @param[in]   actionId                        The action ID for this item
 551          * @param[in]   normalBitmap        The normal bitmap of the item
 552          * @param[in]   pPressedBitmap      The pressed bitmap of the item
 553          * @param[in]   pHighlightedBitmap  The highlighted bitmap of the item
 554          * @exception   E_SUCCESS                       The method is successful.
 555          * @exception   E_OUT_OF_RANGE          The specified @c index less than @c 0 or greater than the number of items in %ContextMenu.
 556          * @exception   E_SYSTEM                        A system error has occurred.
 557          */
 558         result SetItemAt(int index, const Tizen::Base::String& text, int actionId, const Tizen::Graphics::Bitmap& normalBitmap, const Tizen::Graphics::Bitmap* pPressedBitmap = null, const Tizen::Graphics::Bitmap* pHighlightedBitmap = null);
 559
 560         /**
 561          * Removes the item at the specified index from the %ContextMenu control.
 562          *
 563          * @since               2.0
 564          *
 565          * @return              An error code
 566          * @param[in]   index                   The location
 567          * @exception   E_SUCCESS               The method is successful.
 568          * @exception   E_OUT_OF_RANGE  The specified @c index less than @c 0 or greater than the number of items in %ContextMenu.
 569          * @exception   E_SYSTEM                A system error has occurred.
 570          */
 571         result RemoveItemAt(int index);
 572
 573         /**
 574          * Removes all items from the %ContextMenu control.
 575          *
 576          * @since               2.0
 577          *
 578          * @exception   E_SUCCESS               The method is successful.
 579          * @exception   E_SYSTEM                A system error has occurred.
 580          */
 581         result RemoveAllItems(void);
 582
 583         /**
 584          * Gets the number of items of the %ContextMenu control.
 585          *
 586          * @since       2.0
 587          *
 588          * @return      The number of items registered for %ContextMenu, @n
 589          *                      else @c -1 if an error occurs
 590          */
 591         int GetItemCount(void) const;
 592
 593         /**
 594          * Gets the index of the item with the specified action ID.
 595          *
 596          * @since               2.0
 597          *
 598          * @return              The index of the item, @n
 599          *                              else @c -1 if an error occurs
 600          * @param[in]   actionId        The action ID
 601          */
 602         int GetItemIndexFromActionId(int actionId) const;
 603
 604         /**
 605          * Gets the action ID of the item at the specified index.
 606          *
 607          * @since               2.0
 608          *
 609          * @return              The action ID of the item, @n
 610          *                              else @c -1 if the specified index is invalid
 611          * @param[in]   index           The index of the item
 612          */
 613         int GetItemActionIdAt(int index) const;
 614
 615         /**
 616          * Gets the item text color of the %ContextMenu control for the specified status.
 617          *
 618          * @since               2.0
 619          *
 620          * @return      The item text color, @n
 621          *                              else RGBA (0,0,0,0) if an error occurs
 622          * @param[in]   status          The item status
 623          */
 624         Tizen::Graphics::Color GetItemTextColor(ContextMenuItemStatus status) const;
 625
 626         /**
 627          * Sets the item text color of the %ContextMenu control for the specified status.
 628          *
 629          * @since               2.0
 630          *
 631          * @return      An error code
 632          * @param[in]   status                          The item status
 633          * @param[in]   color                           The item text color to set
 634          * @exception   E_SUCCESS                       The method is successful.
 635          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 636          * @exception   E_SYSTEM                        A system error has occurred.
 637          */
 638         result SetItemTextColor(ContextMenuItemStatus status, const Tizen::Graphics::Color& color);
 639
 640         /**
 641          * Sets the position of the anchor.
 642          *
 643          * @since               2.0
 644          *
 645          * @return              An error code
 646          * @param[in]   position                        The new position
 647          * @exception   E_SUCCESS                       The method is successful.
 648          * @exception   E_INVALID_STATE         This instance is in an invalid state.
 649          * @remarks             The x and y coordinates of the anchor are defined in the coordinate space of its parent,
 650          *                              which means that x and y must be defined relative to the top-left corner (0,0) of its parent.
 651          */
 652         result SetAnchorPosition(const Tizen::Graphics::Point& position);
 653
 654         /**
 655          * Sets the position of the anchor.
 656          *
 657          * @since               2.1
 658          *
 659          * @return              An error code
 660          * @param[in]   position                        The new position
 661          * @exception   E_SUCCESS                       The method is successful.
 662          * @exception   E_INVALID_STATE         This instance is in an invalid state.
 663          * @remarks             The x and y coordinates of the anchor are defined in the coordinate space of its parent,
 664          *                              which means that x and y must be defined relative to the top-left corner (0,0) of its parent.
 665          */
 666         result SetAnchorPosition(const Tizen::Graphics::FloatPoint& position);
 667
 668         /**
 669          * Gets the position of the anchor.
 670          *
 671          * @since               2.0
 672          *
 673          * @return              The position of the anchor @n
 674          *                              The coordinate of the anchor position is defined from the top-left corner of its parent Container.
 675          */
 676         Tizen::Graphics::Point GetAnchorPosition(void) const;
 677
 678         /**
 679          * Gets the position of the anchor.
 680          *
 681          * @since               2.1
 682          *
 683          * @return              The position of the anchor @n
 684          *                              The coordinate of the anchor position is defined from the top-left corner of its parent Container.
 685          */
 686         Tizen::Graphics::FloatPoint GetAnchorPositionF(void) const;
 687
 688         /**
 689          * Gets the color of the %ContextMenu control.
 690          *
 691          * @since               2.0
 692          *
 693          * @return              The color of %ContextMenu control, @n
 694          *                              else RGBA(0, 0, 0, 0) if an error occurs
 695          * @see                 SetColor()
 696          */
 697         Tizen::Graphics::Color GetColor(void) const;
 698
 699         /**
 700          * Sets the color of the %ContextMenu control.
 701          *
 702          * @since               2.0
 703          *
 704          * @return              An error code
 705          * @param[in]   color                           The color to set
 706          * @exception   E_SUCCESS                       The method is successful.
 707          * @exception   E_INVALID_STATE         This instance is in an invalid state.
 708          * @exception   E_SYSTEM                        A system error has occurred.
 709          * @see                 GetColor()
 710          */
 711         result SetColor(const Tizen::Graphics::Color& color);
 712
 713         /**
 714          * Gets the item color for the specified status.
 715          *
 716          * @since               2.0
 717          *
 718          * @return              The color of %ContextMenu control, @n
 719          *                      else RGBA(0, 0, 0, 0) if an error occurs
 720          * @param[in]   status                          The menu item status @n
 721          *                                                              The item color for the @c CONTEXT_MENU_ITEM_STATUS_NORMAL status is always the same as the
 722          *                                                              color of the %ContextMenu control.
 723          * @exception   E_SUCCESS                       The method is successful.
 724          * @exception   E_INVALID_ARG           The specified input parameter is invalid. @n
 725          *                                                              The item color for @c CONTEXT_MENU_ITEM_STATUS_NORMAL is not supported.
 726          * @exception   E_INVALID_STATE         This instance is in an invalid state.
 727          * @exception   E_SYSTEM                        A system error has occurred.
 728          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 729          * @see                 SetItemColor()
 730          */
 731         Tizen::Graphics::Color GetItemColor(ContextMenuItemStatus status) const;
 732
 733         /**
 734          * Sets the item color for the specified status.
 735          *
 736          * @since               2.0
 737          *
 738          * @return              An error code
 739          * @param[in]   status                          The menu item status @n
 740          *                                                              The item color for the @c CONTEXT_MENU_ITEM_STATUS_NORMAL status is always the same
 741          *                                                              as the color of the %ContextMenu control.
 742          * @param[in]   color                                   The color to set
 743          * @exception   E_SUCCESS                       The method is successful.
 744          * @exception   E_INVALID_ARG           The specified input parameter is invalid. @n
 745          *                                                              The item color for @c CONTEXT_MENU_ITEM_STATUS_NORMAL is not supported.
 746          * @exception   E_INVALID_STATE         This instance is in an invalid state.
 747          * @exception   E_SYSTEM                        A system error has occurred.
 748          * @see                 GetItemColor()
 749          */
 750         result SetItemColor(ContextMenuItemStatus status, const Tizen::Graphics::Color& color);
 751
 752         /**
 753          * Gets maximum number of visible items.
 754          *
 755          * @since               2.0
 756          *
 757          * @return              The maximum number of visible items, @n
 758          *                              else @c -1 if an error occurs
 759          * @see                 SetMaxVisibleItemsCount()
 760          */
 761         int GetMaxVisibleItemsCount(void) const;
 762
 763         /**
 764          * Sets maximum number of visible items.
 765          *
 766          * @since               2.0
 767          *
 768          * @return              An error code
 769          * @param[in]   maxItemsCount           The maximum number of the visible menu items @n
 770          *                                                              The value should be greater than @c 0 and less than @c 8, and the default value of the visible menu items is @c 4.
 771          * @exception   E_SUCCESS                       The method is successful.
 772          * @exception   E_OUT_OF_RANGE          The specified parameter is out of possible range.
 773          * @exception   E_INVALID_STATE         This instance is in an invalid state.
 774          * @exception   E_SYSTEM                        A system error has occurred.
 775          * @see                 GetMaxVisibleItemsCount()
 776          */
 777         result SetMaxVisibleItemsCount(int maxItemsCount);
 778
 779 protected:
 780         friend class _ContextMenuImpl;
 781 private:
 782         //
 783         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 784         //
 785         // @since       2.0
 786         //
 787         //
 788         ContextMenu(const ContextMenu& rhs);
 789
 790         //
 791         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 792         //
 793         // @since       2.0
 794         //
 795         //
 796         ContextMenu& operator =(const ContextMenu& rhs);
 797 }; // ContextMenu
 798
 799 }}} // Tizen::Ui: Control
 800
 801 #endif // _FUI_CTRL_CONTEXT_MENU_H_