inc/FUiCtrlCustomItem.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        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 <FGrpRectangle.h>
  33 #include <FUiCtrlControlsTypes.h>
  34 #include <FUiCtrlICustomElement.h>
  35 #include <FUiCtrlListItemBase.h>
  36 #include <FUiCtrlListViewTypes.h>
  37
  38 namespace Tizen { namespace Ui { namespace Controls
  39 {
  40
  41 class _CustomItemImpl;
  42
  43 /**
  44  * @class       CustomItem
  45  * @brief    This class defines the common behavior for %CustomItem.
  46  *
  47  * @since       2.0
  48  *
  49  * 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.
  50  *
  51  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/implementing_listviews.htm">ListViews</a>.
  52  *
  53  */
  54
  55 class _OSP_EXPORT_ CustomItem
  56         : public ListItemBase
  57 {
  58 public:
  59         /**
  60          * The object is not fully constructed after this constructor is
  61          * called. For full construction, the Construct() method must be
  62          * called right after calling this constructor.
  63          *
  64          * @since       2.0
  65          */
  66         CustomItem(void);
  67
  68         /**
  69          * This destructor overrides Tizen::Base::Object::~Object().
  70          *
  71          * @since       2.0
  72          */
  73         virtual ~CustomItem(void);
  74
  75         /**
  76          * Initializes this instance of %CustomItem with the specified parameters.
  77          *
  78          * @since       2.0
  79          *
  80          * @return  An error code
  81          * @param[in] itemSize          The size of the item
  82          * @param[in] style             The style of the annex
  83          * @exception E_SUCCESS         The method is successful.
  84          * @exception E_SYSTEM          A system error has occurred.
  85          */
  86         result Construct(const Tizen::Graphics::Dimension& itemSize, ListAnnexStyle style);
  87
  88         /**
  89          * Adds an instance of EnrichedText as an element to the %CustomItem control.
  90          *
  91          * @since       2.0
  92          *
  93          * @return  An error code
  94          * @param[in] rect              The bounds of the element
  95          * @param[in] elementId         The element ID
  96          * @param[in] text              The instance of EnrichedText
  97          * @exception E_SUCCESS         The method is successful.
  98          * @exception E_INVALID_ARG     A specified input parameter is invalid.
  99          * @exception E_SYSTEM          A system error has occurred.
 100          */
 101         result AddElement(const Tizen::Graphics::Rectangle& rect, int elementId, const Tizen::Graphics::EnrichedText& text);
 102
 103         /**
 104          * Adds the text 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 text string to add
 112          * @param[in] textSliding       Set to @c true to allow a long text to slide, @n
 113          *                              else @c false
 114          * @exception E_SUCCESS         The method is successful.
 115          * @exception E_INVALID_ARG     A specified input parameter is invalid.
 116          * @exception E_SYSTEM          A system error has occurred.
 117          * @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
 118          *          automatically when the user long-presses.
 119          */
 120         result AddElement(const Tizen::Graphics::Rectangle& rect, int elementId, const Tizen::Base::String& text, bool textSliding = true);
 121
 122         /**
 123          * Adds the text as an element to the %CustomItem control.
 124          *
 125          * @since       2.0
 126          *
 127          * @return  An error code
 128          * @param[in] rect                  The bounds of the element
 129          * @param[in] elementId             The element ID
 130          * @param[in] text                  The text string to add
 131          * @param[in] textSize              The size of the text
 132          * @param[in] normalTextColor       The color of the text in the normal status
 133          * @param[in] pressedTextColor      The color of the text in the pressed status
 134          * @param[in] highlightedTextColor  The color of the text in the highlighted status
 135          * @param[in] textSliding           Set to @c true to allow a long text to slide, @n
 136          *                                  else @c false
 137          * @exception E_SUCCESS             The method is successful.
 138          * @exception E_INVALID_ARG         A specified input parameter is invalid.
 139          * @exception E_SYSTEM              A system error has occurred.
 140          * @remarks  The default size of text is 38 on a WVGA screen, 22 on a HVGA screen and 20 on a WQVGA screen.
 141          */
 142         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);
 143
 144         /**
 145          * Adds the bitmap image as an element to the %CustomItem control.
 146          *
 147          * @since       2.0
 148          *
 149          * @return  An error code
 150          * @param[in] rect                  The bounds of the element
 151          * @param[in] elementId             The element ID
 152          * @param[in] normalBitmap          The bitmap image displayed when the item is in normal status
 153          * @param[in] pPressedBitmap        The bitmap image displayed when the item is pressed
 154          * @param[in] pHighlightedBitmap    The bitmap image displayed when the item is highlighted
 155          * @exception E_SUCCESS             The method is successful.
 156          * @exception E_INVALID_ARG         A specified input parameter is invalid.
 157          * @exception E_SYSTEM              A system error has occurred.
 158          */
 159         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);
 160
 161         /**
 162          * Adds the custom drawing element to the %CustomItem control.
 163          *
 164          * @since       2.0
 165          *
 166          * @return  An error code
 167          * @param[in] rect              The bounds of the element
 168          * @param[in] elementId         The element ID
 169          * @param[in] element           The custom element
 170          * @exception E_SUCCESS         The method is successful.
 171          * @exception E_INVALID_ARG     A specified input parameter is invalid.
 172          * @exception E_SYSTEM          A system error has occurred.
 173          */
 174         result AddElement(const Tizen::Graphics::Rectangle& rect, int elementId, const ICustomElement& element);
 175
 176         /**
 177          * Removes the element from the %CustomItem control.
 178          *
 179          * @since       2.0
 180          *
 181          * @return  An error code
 182          * @exception E_SUCCESS         The method is successful.
 183          * @exception E_SYSTEM          A system error has occurred.
 184          */
 185         result RemoveAllElements(void);
 186
 187         /**
 188         * Removes the element with the specified element ID.
 189         *
 190         * @since        2.0
 191         *
 192         * @return       An error code
 193         * @param[in] elementId                  The element ID
 194         * @exception E_SUCCESS                  The method is successful.
 195         * @exception E_INVALID_ARG              A specified input parameter is invalid.
 196         * @exception E_SYSTEM                   A system error has occurred.
 197         */
 198         result RemoveElement(int elementId);
 199
 200         /**
 201          * Sets the selection type of an element.
 202          *
 203          * @since       2.0
 204          *
 205          * @param[in] elementId         The element ID
 206          * @param[in] enable            Set to @c true to make only the element selected when touched, @n
 207          *                              else @c false
 208          * @exception E_SUCCESS         The method is successful.
 209          * @exception E_INVALID_ARG     A specified input parameter is invalid.
 210          * @exception E_SYSTEM          A system error has occurred.
 211          * @remarks     Based on the selection type of an element, the area within which the background color changes is different when an element is touched.
 212          */
 213         result SetElementSelectionEnabled(int elementId, bool enable);
 214
 215         /**
 216          * Sets the horizontal alignment of text in the specified element.
 217          *
 218          * @since   2.0
 219          *
 220          * @param[in] elementId         The element ID
 221          * @param[in] alignment                 The horizontal alignment of text
 222          * @exception E_SUCCESS             The method is successful.
 223          * @exception E_INVALID_ARG         A specified input parameter is invalid.
 224          * @exception E_INVALID_OPERATION   The specified element does not handle text.@n
 225          *                                                                      The specified element does not contain text.
 226          * @exception E_SYSTEM              A system error has occurred.
 227          */
 228         result SetElementTextHorizontalAlignment(int elementId, HorizontalAlignment alignment);
 229
 230         /**
 231          * Sets the vertical alignment of text in the specified element.
 232          *
 233          * @since   2.0
 234          *
 235          * @param[in] elementId         The element ID
 236          * @param[in] alignment                 The vertical alignment of text
 237          * @exception E_SUCCESS             The method is successful.
 238          * @exception E_INVALID_ARG         A specified input parameter is invalid.
 239          * @exception E_INVALID_OPERATION   The specified element does not handle text.@n
 240          *                                                                      The specified element does not contain text.
 241          * @exception E_SYSTEM              A system error has occurred.
 242          */
 243         result SetElementTextVerticalAlignment(int elementId, VerticalAlignment alignment);
 244
 245         /**
 246          * Sets the auto-link mask.
 247          *
 248          * @since   2.0
 249          *
 250          * @return  An error code
 251          * @param[in] elementId     The element ID
 252          * @param[in] mask          The auto-link mask @n
 253          *                                                      Multiple link types can be combined using bitwise OR operator (see Tizen::Base::Utility::LinkType). @n
 254          *                                                      For more information, see <a href="../org.tizen.native.appprogramming/html/guide/ui/auto_link_detection.htm">AutoLink Detection</a>.
 255          * @exception E_SUCCESS             The method is successful.
 256          * @exception E_INVALID_ARG         A specified input parameter is invalid.
 257          * @exception E_INVALID_OPERATION   The specified element does not handle text.
 258          * @exception E_SYSTEM              A system error has occurred.
 259          * @remarks     When @c mask is set to @c 0, the auto-link detection is disabled.
 260          * @see Tizen::Base::Utility::LinkType
 261          */
 262         result SetElementAutoLinkMask(int elementId, unsigned long mask);
 263
 264 private:
 265         //
 266         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 267         //
 268         CustomItem(const CustomItem& rhs);
 269
 270         //
 271         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 272         //
 273         CustomItem& operator =(const CustomItem& rhs);
 274 }; // CustomItem
 275
 276 }}} // Tizen::Ui::Controls
 277
 278 #endif // _FUI_CTRL_CUSTOM_ITEM_H_
 279