2 // Open Service Platform
3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
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
9 // http://www.apache.org/licenses/LICENSE-2.0/
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.
19 * @file FUiCtrlOptionMenu.h
20 * @brief This is the header file for the %OptionMenu class.
22 * This header file contains the declarations of the %OptionMenu class and its helper classes.
25 #ifndef _FUI_CTRL_OPTION_MENU_H_
26 #define _FUI_CTRL_OPTION_MENU_H_
28 #include <FBaseTypes.h>
29 #include <FBaseString.h>
30 #include <FUiWindow.h>
31 #include <FUiIActionEventListener.h>
33 namespace Tizen { namespace Ui { namespace Controls
37 * @enum OptionMenuItemStatus
39 * Defines the possible states of the %OptionMenu control item.
43 enum OptionMenuItemStatus
45 OPTION_MENU_ITEM_STATUS_NORMAL, /**< The normal state */
46 OPTION_MENU_ITEM_STATUS_PRESSED, /**< The pressed state */
47 OPTION_MENU_ITEM_STATUS_HIGHLIGHTED /**< The highlighted state */
53 * @brief This class defines a common behavior for an %OptionMenu control.
57 * The %OptionMenu class defines a common behavior for an %OptionMenu control.
58 * An %OptionMenu is used to present users with multiple options. Hierarchical menu
59 * of depth 2 can be constructed. Option menu consists of main items and sub-items.
60 * Unlike ContextMenu, menus cannot display bitmaps.
62 * If an application wants to perform tasks when a menu item is selected, it must
63 * implement IActionEventListener and register the listener by calling the
64 * OptionMenu::AddActionEventListener() method. It will then receive action ID associated
66 * Note that %OptionMenu cannot be used in a Popup.
68 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/implementing_optionmenu.htm">OptionMenu</a>.
70 * The following examples demonstrate how to use an %OptionMenu control.
73 // Sample code for OptionMenuSample.h
76 class OptionMenuSample
77 : public Tizen::Ui::Controls::Form
78 , public Tizen::Ui::IActionEventListener
79 , public Tizen::Ui::Controls::IFormMenuEventListener
82 bool Initialize(void) ;
83 void ShowOptionMenu(void);
85 virtual result OnInitializing(void);
86 virtual result OnTerminating(void);
88 // IActionEventListener
89 virtual void OnActionPerformed(const Tizen::Ui::Control& source, int actionId);
91 // IFormMenuEventListener
92 virtual void OnFormMenuRequested(Tizen::Ui::Controls::Form& source);
95 static const int ID_OPTIONMENU_ITEM1 = 101;
96 static const int ID_OPTIONMENU_ITEM2 = 102;
98 Tizen::Ui::Controls::OptionMenu* __pOptionMenu;
103 // Sample code for OptionMenuSample.cpp
104 #include "OptionMenuSample.h"
106 using namespace Tizen::Ui;
107 using namespace Tizen::Ui::Controls;
110 OptionMenuSample::Initialize()
112 Construct(FORM_STYLE_NORMAL);
117 OptionMenuSample::OnInitializing(void)
119 result r = E_SUCCESS;
121 // Set the FormMenu event listener
122 SetFormMenuEventListener(this);
124 // Creates an instance of OptionMenu
125 __pOptionMenu = new OptionMenu();
126 __pOptionMenu->Construct();
127 __pOptionMenu->AddItem("Item1",ID_OPTIONMENU_ITEM1);
128 __pOptionMenu->AddItem("Item2",ID_OPTIONMENU_ITEM2);
129 __pOptionMenu->AddActionEventListener(*this);
135 OptionMenuSample::OnTerminating(void)
137 result r = E_SUCCESS;
138 delete __pOptionMenu;
143 OptionMenuSample::ShowOptionMenu(void)
145 __pOptionMenu->SetShowState(true);
146 __pOptionMenu->Show();
149 // IActionEventListener implementation
151 OptionMenuSample::OnActionPerformed(const Control& source, int actionId)
155 case ID_OPTIONMENU_ITEM1:
160 case ID_OPTIONMENU_ITEM2:
170 // IFormMenuEventListener implementation
172 OptionMenuSample::OnFormMenuRequested(Tizen::Ui::Controls::Form& source)
178 class _OSP_EXPORT_ OptionMenu
179 : public Tizen::Ui::Window
183 * The object is not fully constructed after this constructor is called. @n
184 * For full construction, the OptionMenu::Construct() method must be called right after calling this constructor.
191 * This polymorphic destructor should be overridden if required.@n
192 * This way, the destructors of the derived classes are called when the destructor of this interface is called.
196 virtual ~OptionMenu(void);
199 * Initializes this instance of %OptionMenu.
203 * @return An error code
204 * @exception E_SUCCESS The method is successful.
205 * @exception E_SYSTEM The method has failed.
207 result Construct(void);
210 * Adds a listener instance to receive action events from this control. @n
211 * The added listener can listen to events on the given event dispatcher's context when they are fired.
215 * @param[in] listener The event listener to add
217 void AddActionEventListener(Tizen::Ui::IActionEventListener& listener);
220 * Removes the specified action event listener so that it no longer receives events from this control.
224 * @param[in] listener The event listener to remove
226 void RemoveActionEventListener(Tizen::Ui::IActionEventListener& listener);
229 * Appends a new item to the end of %OptionMenu.
233 * @return An error code
234 * @param[in] text The text string of the item to append
235 * @param[in] actionId The action ID set by user @n
236 * This will be given as a parameter to Tizen::Ui::IActionEventListener::OnActionPerformed() callback.
237 * @exception E_SUCCESS The method is successful.
238 * @exception E_SYSTEM The method has failed.
239 * @remarks %OptionMenu can have a maximum of @c 12 main items.
241 result AddItem(const Tizen::Base::String& text, int actionId);
244 * Appends a new item to the end of %OptionMenu.
248 * @return An error code
249 * @param[in] normalBitmap The normal bitmap of the item
250 * @param[in] pPressedBitmap The pressed bitmap of the item
251 * @param[in] pHighlightedBitmap The highlighted bitmap of the item
252 * @param[in] actionId The action ID set by user. @n
253 * This will be given as a parameter to Tizen::Ui::IActionEventListener::OnActionPerformed() callback.
254 * @exception E_SUCCESS The method is successful.
255 * @exception E_SYSTEM The method has failed.
256 * @remarks When a user navigates the user interface using the directional keys, @n
257 * the selected UI control is highlighted and the control takes the focus.
259 result AddItem (const Tizen::Graphics::Bitmap& normalBitmap, const Tizen::Graphics::Bitmap* pPressedBitmap, const Tizen::Graphics::Bitmap* pHighlightedBitmap, int actionId);
262 * Appends a new item to the end of %OptionMenu.
266 * @return An error code
267 * @param[in] text The text string of the item to append
268 * @param[in] actionId The action ID set by user @n
269 * This will be given as a parameter to Tizen::Ui::IActionEventListener::OnActionPerformed() callback.
270 * @param[in] normalBitmap The normal bitmap of the item
271 * @param[in] pPressedBitmap The pressed bitmap of the item
272 * @param[in] pHighlightedBitmap The highlighted bitmap of the item
273 * @exception E_SUCCESS The method is successful.
274 * @exception E_SYSTEM The method has failed.
276 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);
279 * Inserts a specific item at the given index of %OptionMenu.
283 * @return An error code
284 * @param[in] mainIndex The main index
285 * @param[in] text The text string of the item to set
286 * @param[in] actionId The action ID set by user @n
287 * This will be given as a parameter to Tizen::Ui::IActionEventListener::OnActionPerformed() callback.
288 * @exception E_SUCCESS The method is successful.
289 * @exception E_INVALID_ARG A specified parameter is invalid.
290 * @exception E_SYSTEM The method has failed.
292 result InsertItemAt(int mainIndex, const Tizen::Base::String& text, int actionId);
295 * Inserts a specific item at the given index of %OptionMenu.
299 * @return An error code
300 * @param[in] mainIndex The main index
301 * @param[in] normalBitmap The normal bitmap of the item
302 * @param[in] pPressedBitmap The pressed bitmap of the item
303 * @param[in] pHighlightedBitmap The highlighted bitmap of the item
304 * @param[in] actionId The action ID set by user. @n
305 * This will be given as a parameter to Tizen::Ui::IActionEventListener::OnActionPerformed() callback.
306 * @exception E_SUCCESS The method is successful.
307 * @exception E_INVALID_ARG A specified parameter is invalid.
308 * @remarks When a user navigates the user interface using the directional keys, @n
309 * the selected UI control is highlighted and the control takes the focus.
311 result InsertItemAt (int mainIndex, const Tizen::Graphics::Bitmap& normalBitmap, const Tizen::Graphics::Bitmap* pPressedBitmap, const Tizen::Graphics::Bitmap* pHighlightedBitmap, int actionId);
314 * Inserts a specific item at the given index of %OptionMenu.
318 * @return An error code
319 * @param[in] mainIndex The main index
320 * @param[in] text The text string of the item to append
321 * @param[in] actionId The action ID set by user. @n
322 * This will be given as a parameter to Tizen::Ui::IActionEventListener::OnActionPerformed() callback.
323 * @param[in] normalBitmap The normal bitmap of the item
324 * @param[in] pPressedBitmap The pressed bitmap of the item
325 * @param[in] pHighlightedBitmap The highlighted bitmap of the item
326 * @exception E_SUCCESS The method is successful.
327 * @exception E_INVALID_ARG A specified parameter is invalid.
328 * @exception E_SYSTEM The method has failed.
330 result InsertItemAt (int mainIndex, const Tizen::Base::String& text, int actionId, const Tizen::Graphics::Bitmap& normalBitmap, const Tizen::Graphics::Bitmap* pPressedBitmap=null, const Tizen::Graphics::Bitmap* pHighlightedBitmap=null);
333 * Sets a specific item at the given index of %OptionMenu.
337 * @return An error code
338 * @param[in] mainIndex The main index
339 * @param[in] text The text string of the item to set
340 * @param[in] actionId The action ID set by user @n
341 * This will be given as a parameter to Tizen::Ui::IActionEventListener::OnActionPerformed() callback.
342 * @exception E_SUCCESS The method is successful.
343 * @exception E_INVALID_ARG A specified parameter is invalid.
344 * @exception E_SYSTEM The method has failed.
346 result SetItemAt(int mainIndex, const Tizen::Base::String& text, int actionId);
349 * Sets a specific item at the given index of %OptionMenu.
353 * @return An error code
354 * @param[in] mainIndex The main index
355 * @param[in] normalBitmap The normal bitmap of the item
356 * @param[in] pPressedBitmap The pressed bitmap of the item
357 * @param[in] pHighlightedBitmap The highlighted bitmap of the item
358 * @param[in] actionId The action ID set by user. @n
359 * This will be given as a parameter to Tizen::Ui::IActionEventListener::OnActionPerformed() callback.
360 * @exception E_SUCCESS The method is successful.
361 * @exception E_INVALID_ARG A specified parameter is invalid.
362 * @remarks When a user navigates the user interface using the directional keys, @n
363 * the selected UI control is highlighted and the control takes the focus.
365 result SetItemAt (int mainIndex, const Tizen::Graphics::Bitmap& normalBitmap, const Tizen::Graphics::Bitmap* pPressedBitmap, const Tizen::Graphics::Bitmap* pHighlightedBitmap, int actionId);
368 * Sets a specific item at the given index of %OptionMenu.
372 * @return An error code
373 * @param[in] mainIndex The main index
374 * @param[in] text The text string of the item to set
375 * @param[in] actionId The action ID set by user. @n
376 * This will be given as a parameter to Tizen::Ui::IActionEventListener::OnActionPerformed() callback.
377 * @param[in] normalBitmap The normal bitmap of the item
378 * @param[in] pPressedBitmap The pressed bitmap of the item
379 * @param[in] pHighlightedBitmap The highlighted bitmap of the item
380 * @exception E_SUCCESS The method is successful.
381 * @exception E_INVALID_ARG A specified parameter is invalid.
383 result SetItemAt (int mainIndex, const Tizen::Base::String& text, int actionId, const Tizen::Graphics::Bitmap& normalBitmap, const Tizen::Graphics::Bitmap* pPressedBitmap=null, const Tizen::Graphics::Bitmap* pHighlightedBitmap=null);
386 * Removes the item of a specified index from %OptionMenu.
390 * @return An error code
391 * @param[in] mainIndex The main index
392 * @exception E_SUCCESS The method is successful.
393 * @exception E_INVALID_ARG A specified parameter is invalid.
394 * @exception E_SYSTEM The method has failed.
396 result RemoveItemAt(int mainIndex);
399 * Removes all items from %OptionMenu.
403 void RemoveAllItems (void);
406 * Gets the number of items registered for %OptionMenu.
410 * @return The number of items registered for %OptionMenu
412 int GetItemCount(void) const;
415 * Gets the index of the item with a specified action ID.
419 * @return The index of the item
420 * @param[in] actionId The action ID set by user. @n
421 * This will be given as a parameter to Tizen::Ui::IActionEventListener::OnActionPerformed() callback.
423 int GetItemIndexFromActionId(int actionId) const;
426 * Gets the action ID of the item at a specified index.
430 * @return The action ID of the item
431 * @param[in] mainIndex The index of the item
433 int GetItemActionIdAt(int mainIndex) const;
436 * Appends new sub-item to the end of %OptionMenu.
440 * @return An error code
441 * @param[in] mainIndex The index of the main item
442 * @param[in] text The text string of the item to append
443 * @param[in] actionId The action ID set by user @n
444 * This will be given as a parameter to Tizen::Ui::IActionEventListener::OnActionPerformed() callback.
445 * @exception E_SUCCESS The method is successful.
446 * @exception E_INVALID_ARG A specified parameter is invalid.
447 * @exception E_SYSTEM The method has failed.
449 result AddSubItem(int mainIndex, const Tizen::Base::String& text, int actionId);
452 * Inserts a specific sub-item at the given index of %OptionMenu.
456 * @return An error code
457 * @param[in] mainIndex The index of the main item
458 * @param[in] subIndex The index of the sub-item
459 * @param[in] text The text string of the item to set
460 * @param[in] actionId The action ID set by user. @n
461 * This will be given as a parameter to Tizen::Ui::IActionEventListener::OnActionPerformed() callback.
462 * @exception E_SUCCESS The method is successful.
463 * @exception E_INVALID_ARG A specified parameter is invalid.
464 * @exception E_SYSTEM The method has failed.
466 result InsertSubItemAt(int mainIndex, int subIndex, const Tizen::Base::String& text, int actionId);
469 * Sets a specific sub-item at the given index of %OptionMenu.
473 * @return An error code
474 * @param[in] mainIndex The index of the main item
475 * @param[in] subIndex The index of the sub-item
476 * @param[in] text The text string of the item to set
477 * @param[in] actionId The action ID set by user. @n
478 * This will be given as a parameter to Tizen::Ui::IActionEventListener::OnActionPerformed() callback.
479 * @exception E_SUCCESS The method is successful.
480 * @exception E_INVALID_ARG A specified parameter is invalid.
481 * @exception E_SYSTEM The method has failed.
483 result SetSubItemAt(int mainIndex, int subIndex, const Tizen::Base::String& text, int actionId);
486 * Removes the sub-item of a specified index from %OptionMenu.
490 * @return An error code
491 * @param[in] mainIndex The index of the main item
492 * @param[in] subIndex The index of the sub-item
493 * @exception E_SUCCESS The method is successful.
494 * @exception E_INVALID_ARG A specified parameter is invalid.
495 * @exception E_SYSTEM The method has failed.
497 result RemoveSubItemAt(int mainIndex, int subIndex);
500 * Gets the number of sub-items registered for %OptionMenu.
504 * @return The number of sub-items registered for %OptionMenu
505 * @param[in] mainIndex The index of the main item
507 int GetSubItemCount(int mainIndex) const;
510 * Gets the index of the sub-item with a specified action ID.
514 * @return The index of the item
515 * @param[in] actionId The action ID set by user. @n
516 * This will be given as a parameter to Tizen::Ui::IActionEventListener::OnActionPerformed() callback.
518 int GetSubItemIndexFromActionId(int actionId) const;
521 * Gets the action ID of the sub-item at a specified index.
525 * @return The action ID of the item
526 * @param[in] mainIndex The index of the main item
527 * @param[in] subIndex The index of the sub-item
529 int GetSubItemActionIdAt(int mainIndex, int subIndex) const;
532 * Sets the item text color of %OptionMenu for a specified status.
536 * @return An error code
537 * @param[in] status The item status
538 * @param[in] color The item text color to set
539 * @exception E_SUCCESS The method is successful.
540 * @exception E_INVALID_ARG A specified parameter is invalid.
541 * @see GetItemTextColor()
543 result SetItemTextColor(OptionMenuItemStatus status, const Tizen::Graphics::Color& color);
546 * Gets the item text color of %OptionMenu for a specified status.
550 * @return The item text color, @n
551 * else RGBA (0,0,0,0) if an error occurs
552 * @param[in] status The item status
553 * @see SetItemTextColor()
555 Tizen::Graphics::Color GetItemTextColor(OptionMenuItemStatus status) const;
558 * Sets the item color of %OptionMenu for a specified status.
562 * @return An error code
563 * @param[in] status The item status
564 * @param[in] color The item color to set
565 * @exception E_SUCCESS The method is successful.
566 * @exception E_INVALID_ARG A specified input parameter is invalid. @n
567 * The item color for @c OPTION_MENU_ITEM_STATUS_NORMAL is not supported.
568 * @remarks The item color for the @c OPTION_MENU_ITEM_STATUS_NORMAL status is always the same as the color of the %OptionMenu control.
569 * @see GetItemColor()
571 result SetItemColor(OptionMenuItemStatus status, const Tizen::Graphics::Color& color);
574 * Gets the item color of %OptionMenu for a specified status.
578 * @return The item color, @n
579 * else RGBA(0, 0, 0, 0) if an error occurs
580 * @param[in] status The item status
582 Tizen::Graphics::Color GetItemColor(OptionMenuItemStatus status) const;
585 * Sets the color of %OptionMenu.
589 * @return An error code
590 * @param[in] color The color to set
591 * @exception E_SUCCESS The method is successful.
592 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
595 result SetColor(const Tizen::Graphics::Color& color);
598 * Gets the color of %OptionMenu.
602 * @return The color of %OptionMenu, @n
603 * else RGBA(0, 0, 0, 0) if an error occurs
606 Tizen::Graphics::Color GetColor(void) const;
609 * Sets the maximum number of visible items for %OptionMenu.
613 * @return An error code
614 * @param[in] maxItemsCount The maximum number of visible items @n
615 * The value should be greater than @c 0.
616 * @exception E_SUCCESS The method is successful.
617 * @exception E_INALID_ARG A specified input parameter is invalid.
619 result SetMaxVisibleItemsCount(int maxItemsCount);
622 * Gets the maximum number of visible items for %OptionMenu.
626 * @return The maximum number of visible items, @n
627 * else @c -1 if an error occurs
629 int GetMaxVisibleItemsCount(void) const;
633 // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
635 OptionMenu(const OptionMenu&);
638 // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
640 OptionMenu& operator =(const OptionMenu&);
642 friend class _OptionMenuImpl;
645 }}} // Tizen::Ui::Controls
647 #endif // _FUI_CTRL_OPTION_MENU_H_