inc/FUiCtrlCustomItem.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        FUiCtrlCustomItem.h
  20  * @brief       This is the header file for the %CustomItem class.
  21  *
  22  * This header file contains the declarations of the %CustomItem class and its helper classes.
  23  */
  24
  25 #ifndef _FUI_CTRL_CUSTOM_ITEM_H_
  26 #define _FUI_CTRL_CUSTOM_ITEM_H_
  27
  28 #include <FBaseObject.h>
  29 #include <FBaseTypes.h>
  30 #include <FGrpBitmap.h>
  31 #include <FGrpEnrichedText.h>
  32 #include <FGrpFloatRectangle.h>
  33 #include <FGrpRectangle.h>
  34 #include <FUiCtrlControlsTypes.h>
  35 #include <FUiCtrlICustomElement.h>
  36 #include <FUiCtrlICustomElementF.h>
  37 #include <FUiCtrlListItemBase.h>
  38 #include <FUiCtrlListViewTypes.h>
  39
  40 namespace Tizen { namespace Ui { namespace Controls
  41 {
  42
  43 class _CustomItemImpl;
  44
  45 /**
  46  * @class       CustomItem
  47  * @brief    This class defines the common behavior for %CustomItem.
  48  *
  49  * @since       2.0
  50  *
  51  * The %CustomItem class displays a list item, which is the unit of handling a ListView or GroupedListView. It provides customized formatting of specific list items.
  52  *
  53  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/implementing_listviews.htm">ListViews</a>.
  54  *
  55  */
  56
  57 class _OSP_EXPORT_ CustomItem
  58         : public ListItemBase
  59 {
  60 public:
  61         /**
  62          * The object is not fully constructed after this constructor is
  63          * called. @n For full construction, the %Construct() method must be
  64          * called right after calling this constructor.
  65          *
  66          * @since       2.0
  67          */
  68         CustomItem(void);
  69
  70         /**
  71          * This destructor overrides Tizen::Base::Object::~Object().
  72          *
  73          * @since       2.0
  74          */
  75         virtual ~CustomItem(void);
  76
  77         /**
  78          * Initializes this instance of %CustomItem with the specified parameters.
  79          *
  80          * @since       2.0
  81          *
  82          * @return  An error code
  83          * @param[in] itemSize          The size of the item
  84          * @param[in] style             The style of the annex
  85          * @exception E_SUCCESS         The method is successful.
  86          * @exception E_SYSTEM          A system error has occurred.
  87          */
  88         result Construct(const Tizen::Graphics::Dimension& itemSize, ListAnnexStyle style);
  89
  90         /**
  91          * Initializes this instance of %CustomItem with the specified parameters.
  92          *
  93          * @since       2.1
  94          *
  95          * @return  An error code
  96          * @param[in] itemSize          The size of the item
  97          * @param[in] style             The style of the annex
  98          * @exception E_SUCCESS         The method is successful.
  99          * @exception E_SYSTEM          A system error has occurred.
 100          */
 101         result Construct(const Tizen::Graphics::FloatDimension& itemSize, ListAnnexStyle style);
 102
 103         /**
 104          * Adds an instance of Tizen::Graphics::EnrichedText as an element to the %CustomItem control.
 105          *
 106          * @since       2.0
 107          *
 108          * @return  An error code
 109          * @param[in] rect              The bounds of the element
 110          * @param[in] elementId         The element ID
 111          * @param[in] text              The instance of EnrichedText
 112          * @exception E_SUCCESS         The method is successful.
 113          * @exception E_INVALID_ARG     A specified input parameter is invalid.
 114          * @exception E_SYSTEM          A system error has occurred.
 115          */
 116         result AddElement(const Tizen::Graphics::Rectangle& rect, int elementId, const Tizen::Graphics::EnrichedText& text);
 117
 118         /**
 119          * Adds an instance of Tizen::Graphics::EnrichedText as an element to the %CustomItem control.
 120          *
 121          * @since       2.1
 122          *
 123          * @return  An error code
 124          * @param[in] rect              The bounds of the element
 125          * @param[in] elementId         The element ID
 126          * @param[in] text              The instance of EnrichedText
 127          * @exception E_SUCCESS         The method is successful.
 128          * @exception E_INVALID_ARG     A specified input parameter is invalid.
 129          * @exception E_SYSTEM          A system error has occurred.
 130          */
 131         result AddElement(const Tizen::Graphics::FloatRectangle& rect, int elementId, const Tizen::Graphics::EnrichedText& text);
 132
 133         /**
 134          * Adds the text as an element to the %CustomItem control.
 135          *
 136          * @since       2.0
 137          *
 138          * @return  An error code
 139          * @param[in] rect              The bounds of the element
 140          * @param[in] elementId         The element ID
 141          * @param[in] text              The text string to add
 142          * @param[in] textSliding       Set to @c true to allow a long text to slide, @n
 143          *                              else @c false
 144          * @exception E_SUCCESS         The method is successful.
 145          * @exception E_INVALID_ARG     A specified input parameter is invalid.
 146          * @exception E_SYSTEM          A system error has occurred.
 147          * @remarks     If the width of the specified @c text exceeds the width of the element and @c textSliding is set to @c true, the text slides
 148          *          automatically when the user long-presses.
 149          */
 150         result AddElement(const Tizen::Graphics::Rectangle& rect, int elementId, const Tizen::Base::String& text, bool textSliding = true);
 151
 152         /**
 153          * Adds the text as an element to the %CustomItem control.
 154          *
 155          * @since       2.1
 156          *
 157          * @return  An error code
 158          * @param[in] rect              The bounds of the element
 159          * @param[in] elementId         The element ID
 160          * @param[in] text              The text string to add
 161          * @param[in] textSliding       Set to @c true to allow a long text to slide, @n
 162          *                              else @c false
 163          * @exception E_SUCCESS         The method is successful.
 164          * @exception E_INVALID_ARG     A specified input parameter is invalid.
 165          * @exception E_SYSTEM          A system error has occurred.
 166          * @remarks     If the width of the specified @c text exceeds the width of the element and @c textSliding is set to @c true, the text slides
 167          *          automatically when the user long-presses.
 168          */
 169         result AddElement(const Tizen::Graphics::FloatRectangle& rect, int elementId, const Tizen::Base::String& text, bool textSliding = true);
 170
 171         /**
 172          * Adds the text as an element to the %CustomItem control.
 173          *
 174          * @since       2.0
 175          *
 176          * @return  An error code
 177          * @param[in] rect                  The bounds of the element
 178          * @param[in] elementId             The element ID
 179          * @param[in] text                  The text string to add
 180          * @param[in] textSize              The size of the text @n
 181          *                                              The default size of text is @c 38 on a WVGA screen, @c 22 on a HVGA screen and @c 20 on a WQVGA screen.
 182          * @param[in] normalTextColor       The color of the text in the normal status
 183          * @param[in] pressedTextColor      The color of the text in the pressed status
 184          * @param[in] highlightedTextColor  The color of the text in the highlighted status
 185          * @param[in] textSliding           Set to @c true to allow a long text to slide, @n
 186          *                                  else @c false
 187          * @exception E_SUCCESS             The method is successful.
 188          * @exception E_INVALID_ARG         A specified input parameter is invalid.
 189          * @exception E_SYSTEM              A system error has occurred.
 190          */
 191         result AddElement(const Tizen::Graphics::Rectangle& rect, int elementId, const Tizen::Base::String& text, int textSize, const Tizen::Graphics::Color& normalTextColor, const Tizen::Graphics::Color& pressedTextColor, const Tizen::Graphics::Color& highlightedTextColor, bool textSliding = true);
 192
 193         /**
 194          * Adds the text as an element to the %CustomItem control.
 195          *
 196          * @since       2.1
 197          *
 198          * @return  An error code
 199          * @param[in] rect                  The bounds of the element
 200          * @param[in] elementId             The element ID
 201          * @param[in] text                  The text string to add
 202          * @param[in] textSize              The size of the text @n
 203          *                                              The default size of text is @c 38 on a WVGA screen, @c 22 on a HVGA screen and @c 20 on a WQVGA screen.
 204          * @param[in] normalTextColor       The color of the text in the normal status
 205          * @param[in] pressedTextColor      The color of the text in the pressed status
 206          * @param[in] highlightedTextColor  The color of the text in the highlighted status
 207          * @param[in] textSliding           Set to @c true to allow a long text to slide, @n
 208          *                                  else @c false
 209          * @exception E_SUCCESS             The method is successful.
 210          * @exception E_INVALID_ARG         A specified input parameter is invalid.
 211          * @exception E_SYSTEM              A system error has occurred.
 212          */
 213         result AddElement(const Tizen::Graphics::FloatRectangle& rect, int elementId, const Tizen::Base::String& text, float textSize, const Tizen::Graphics::Color& normalTextColor, const Tizen::Graphics::Color& pressedTextColor, const Tizen::Graphics::Color& highlightedTextColor, bool textSliding = true);
 214
 215         /**
 216          * Adds the bitmap image as an element to the %CustomItem control.
 217          *
 218          * @since       2.0
 219          *
 220          * @return  An error code
 221          * @param[in] rect                  The bounds of the element
 222          * @param[in] elementId             The element ID
 223          * @param[in] normalBitmap          The bitmap image displayed when the item is in normal status
 224          * @param[in] pPressedBitmap        The bitmap image displayed when the item is pressed
 225          * @param[in] pHighlightedBitmap    The bitmap image displayed when the item is highlighted
 226          * @exception E_SUCCESS             The method is successful.
 227          * @exception E_INVALID_ARG         A specified input parameter is invalid.
 228          * @exception E_SYSTEM              A system error has occurred.
 229          */
 230         result AddElement(const Tizen::Graphics::Rectangle& rect, int elementId, const Tizen::Graphics::Bitmap& normalBitmap, const Tizen::Graphics::Bitmap* pPressedBitmap = NULL, const Tizen::Graphics::Bitmap* pHighlightedBitmap = NULL);
 231
 232         /**
 233          * Adds the bitmap image as an element to the %CustomItem control.
 234          *
 235          * @since       2.1
 236          *
 237          * @return  An error code
 238          * @param[in] rect                  The bounds of the element
 239          * @param[in] elementId             The element ID
 240          * @param[in] normalBitmap          The bitmap image displayed when the item is in normal status
 241          * @param[in] pPressedBitmap        The bitmap image displayed when the item is pressed
 242          * @param[in] pHighlightedBitmap    The bitmap image displayed when the item is highlighted
 243          * @exception E_SUCCESS             The method is successful.
 244          * @exception E_INVALID_ARG         A specified input parameter is invalid.
 245          * @exception E_SYSTEM              A system error has occurred.
 246          */
 247         result AddElement(const Tizen::Graphics::FloatRectangle& rect, int elementId, const Tizen::Graphics::Bitmap& normalBitmap, const Tizen::Graphics::Bitmap* pPressedBitmap = NULL, const Tizen::Graphics::Bitmap* pHighlightedBitmap = NULL);
 248
 249         /**
 250          * Adds the custom drawing element to the %CustomItem control.
 251          *
 252          * @brief       <i> [Deprecated] </i>
 253          * @deprecated  This method is deprecated.
 254          * @since       2.0
 255          *
 256          * @return  An error code
 257          * @param[in] rect              The bounds of the element
 258          * @param[in] elementId         The element ID
 259          * @param[in] element           The custom element
 260          * @exception E_SUCCESS         The method is successful.
 261          * @exception E_INVALID_ARG     A specified input parameter is invalid.
 262          * @exception E_SYSTEM          A system error has occurred.
 263          */
 264         result AddElement(const Tizen::Graphics::Rectangle& rect, int elementId, const ICustomElement& element);
 265
 266         /**
 267          * Adds the custom drawing element to the %CustomItem control.
 268          *
 269          * @since       2.1
 270          *
 271          * @return  An error code
 272          * @param[in] rect              The bounds of the element
 273          * @param[in] elementId         The element ID
 274          * @param[in] element           The custom element
 275          * @exception E_SUCCESS         The method is successful.
 276          * @exception E_INVALID_ARG     A specified input parameter is invalid.
 277          * @exception E_SYSTEM          A system error has occurred.
 278          */
 279         result AddElement(const Tizen::Graphics::Rectangle& rect, int elementId, ICustomElement& element);
 280
 281         /**
 282          * Adds a custom drawing element to the %CustomItem control.
 283          *
 284          * @since       2.1
 285          *
 286          * @return  An error code
 287          * @param[in] rect              The bounds of the element
 288          * @param[in] elementId         The element ID
 289          * @param[in] element           The custom element
 290          * @exception E_SUCCESS         The method is successful.
 291          * @exception E_INVALID_ARG     A specified input parameter is invalid.
 292          * @exception E_SYSTEM          A system error has occurred.
 293          */
 294         result AddElement(const Tizen::Graphics::FloatRectangle& rect, int elementId, ICustomElementF& element);
 295
 296         /**
 297          * Removes the element from the %CustomItem control.
 298          *
 299          * @since       2.0
 300          *
 301          * @return  An error code
 302          * @exception E_SUCCESS         The method is successful.
 303          * @exception E_SYSTEM          A system error has occurred.
 304          */
 305         result RemoveAllElements(void);
 306
 307         /**
 308         * Removes the element with the specified element ID.
 309         *
 310         * @since        2.0
 311         *
 312         * @return       An error code
 313         * @param[in] elementId                  The element ID
 314         * @exception E_SUCCESS                  The method is successful.
 315         * @exception E_INVALID_ARG              A specified input parameter is invalid.
 316         * @exception E_SYSTEM                   A system error has occurred.
 317         */
 318         result RemoveElement(int elementId);
 319
 320         /**
 321          * Sets the selection type of an element.
 322          *
 323          * @since       2.0
 324          *
 325          * @param[in] elementId         The element ID
 326          * @param[in] enable            Set to @c true to make only the element selected when touched, @n
 327          *                              else @c false
 328          * @exception E_SUCCESS         The method is successful.
 329          * @exception E_INVALID_ARG     A specified input parameter is invalid.
 330          * @exception E_SYSTEM          A system error has occurred.
 331          * @remarks     Based on the selection type of an element, the area within which the background color changes is different when an element is touched.
 332          */
 333         result SetElementSelectionEnabled(int elementId, bool enable);
 334
 335         /**
 336          * Sets the horizontal alignment of text in the specified element.
 337          *
 338          * @since   2.0
 339          *
 340          * @param[in] elementId         The element ID
 341          * @param[in] alignment                 The horizontal alignment of text
 342          * @exception E_SUCCESS             The method is successful.
 343          * @exception E_INVALID_ARG         A specified input parameter is invalid.
 344          * @exception E_INVALID_OPERATION   The specified element either does not handle text or does not contain text.
 345          * @exception E_SYSTEM              A system error has occurred.
 346          */
 347         result SetElementTextHorizontalAlignment(int elementId, HorizontalAlignment alignment);
 348
 349         /**
 350          * Sets the vertical alignment of text in the specified element.
 351          *
 352          * @since   2.0
 353          *
 354          * @param[in] elementId         The element ID
 355          * @param[in] alignment                 The vertical alignment of text
 356          * @exception E_SUCCESS             The method is successful.
 357          * @exception E_INVALID_ARG         A specified input parameter is invalid.
 358          * @exception E_INVALID_OPERATION   The specified element either does not handle text or does not contain text.
 359          * @exception E_SYSTEM              A system error has occurred.
 360          */
 361         result SetElementTextVerticalAlignment(int elementId, VerticalAlignment alignment);
 362
 363         /**
 364          * Sets the auto-link mask.
 365          *
 366          * @since   2.0
 367          *
 368          * @return  An error code
 369          * @param[in] elementId     The element ID
 370          * @param[in] mask          The auto-link mask @n
 371          *                              Multiple link types of Tizen::Base::Utility::LinkType can be combined using bitwise OR operator. @n For more information,
 372          *                              see <a href="../org.tizen.native.appprogramming/html/guide/ui/auto_link_detection.htm">AutoLink Detection</a>. @n
 373          *                              If the value is set to @c 0, the auto-link detection is disabled.
 374          * @exception E_SUCCESS             The method is successful.
 375          * @exception E_INVALID_ARG         A specified input parameter is invalid.
 376          * @exception E_INVALID_OPERATION   The specified element does not handle text.
 377          * @exception E_SYSTEM              A system error has occurred.
 378          */
 379         result SetElementAutoLinkMask(int elementId, unsigned long mask);
 380
 381 private:
 382         //
 383         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 384         //
 385         CustomItem(const CustomItem& rhs);
 386
 387         //
 388         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 389         //
 390         CustomItem& operator =(const CustomItem& rhs);
 391 }; // CustomItem
 392
 393 }}} // Tizen::Ui::Controls
 394
 395 #endif // _FUI_CTRL_CUSTOM_ITEM_H_
 396