2 // Open Service Platform
3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
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
9 // http://floralicense.org/license/
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 FUiCtrlCustomItem.h
20 * @brief This is the header file for the %CustomItem class.
22 * This header file contains the declarations of the %CustomItem class and its helper classes.
25 #ifndef _FUI_CTRL_CUSTOM_ITEM_H_
26 #define _FUI_CTRL_CUSTOM_ITEM_H_
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>
40 namespace Tizen { namespace Ui { namespace Controls
43 class _CustomItemImpl;
47 * @brief This class defines the common behavior for %CustomItem.
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.
53 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/implementing_listviews.htm">ListViews</a>.
57 class _OSP_EXPORT_ CustomItem
62 * The object is not fully constructed after this constructor is
63 * called. For full construction, the Construct() method must be
64 * called right after calling this constructor.
71 * This destructor overrides Tizen::Base::Object::~Object().
75 virtual ~CustomItem(void);
78 * Initializes this instance of %CustomItem with the specified parameters.
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.
88 result Construct(const Tizen::Graphics::Dimension& itemSize, ListAnnexStyle style);
91 * Initializes this instance of %CustomItem with the specified parameters.
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.
101 result Construct(const Tizen::Graphics::FloatDimension& itemSize, ListAnnexStyle style);
104 * Adds an instance of EnrichedText as an element to the %CustomItem control.
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.
116 result AddElement(const Tizen::Graphics::Rectangle& rect, int elementId, const Tizen::Graphics::EnrichedText& text);
119 * Adds an instance of EnrichedText as an element to the %CustomItem control.
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.
131 result AddElement(const Tizen::Graphics::FloatRectangle& rect, int elementId, const Tizen::Graphics::EnrichedText& text);
134 * Adds the text as an element to the %CustomItem control.
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
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.
150 result AddElement(const Tizen::Graphics::Rectangle& rect, int elementId, const Tizen::Base::String& text, bool textSliding = true);
153 * Adds the text as an element to the %CustomItem control.
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
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.
169 result AddElement(const Tizen::Graphics::FloatRectangle& rect, int elementId, const Tizen::Base::String& text, bool textSliding = true);
172 * Adds the text as an element to the %CustomItem control.
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
181 * @param[in] normalTextColor The color of the text in the normal status
182 * @param[in] pressedTextColor The color of the text in the pressed status
183 * @param[in] highlightedTextColor The color of the text in the highlighted status
184 * @param[in] textSliding Set to @c true to allow a long text to slide, @n
186 * @exception E_SUCCESS The method is successful.
187 * @exception E_INVALID_ARG A specified input parameter is invalid.
188 * @exception E_SYSTEM A system error has occurred.
189 * @remarks The default size of text is 38 on a WVGA screen, 22 on a HVGA screen and 20 on a WQVGA screen.
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);
194 * Adds the text as an element to the %CustomItem control.
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
203 * @param[in] normalTextColor The color of the text in the normal status
204 * @param[in] pressedTextColor The color of the text in the pressed status
205 * @param[in] highlightedTextColor The color of the text in the highlighted status
206 * @param[in] textSliding Set to @c true to allow a long text to slide, @n
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 The default size of text is 38 on a WVGA screen, 22 on a HVGA screen and 20 on a WQVGA screen.
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);
216 * Adds the bitmap image as an element to the %CustomItem control.
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.
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);
233 * Adds the bitmap image as an element to the %CustomItem control.
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.
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);
250 * Adds the custom drawing element to the %CustomItem control.
252 * @brief <i> [Deprecated] </i>
253 * @deprecated This API is deprecated.
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.
264 result AddElement(const Tizen::Graphics::Rectangle& rect, int elementId, const ICustomElement& element);
267 * Adds the custom drawing element to the %CustomItem control.
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.
279 result AddElement(const Tizen::Graphics::Rectangle& rect, int elementId, ICustomElement& element);
282 * Adds the custom drawing element to the %CustomItem control.
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.
294 result AddElement(const Tizen::Graphics::FloatRectangle& rect, int elementId, ICustomElementF& element);
297 * Removes the element from the %CustomItem control.
301 * @return An error code
302 * @exception E_SUCCESS The method is successful.
303 * @exception E_SYSTEM A system error has occurred.
305 result RemoveAllElements(void);
308 * Removes the element with the specified element ID.
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.
318 result RemoveElement(int elementId);
321 * Sets the selection type of an element.
325 * @param[in] elementId The element ID
326 * @param[in] enable Set to @c true to make only the element selected when touched, @n
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.
333 result SetElementSelectionEnabled(int elementId, bool enable);
336 * Sets the horizontal alignment of text in the specified element.
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 does not handle text.@n
345 * The specified element does not contain text.
346 * @exception E_SYSTEM A system error has occurred.
348 result SetElementTextHorizontalAlignment(int elementId, HorizontalAlignment alignment);
351 * Sets the vertical alignment of text in the specified element.
355 * @param[in] elementId The element ID
356 * @param[in] alignment The vertical alignment of text
357 * @exception E_SUCCESS The method is successful.
358 * @exception E_INVALID_ARG A specified input parameter is invalid.
359 * @exception E_INVALID_OPERATION The specified element does not handle text.@n
360 * The specified element does not contain text.
361 * @exception E_SYSTEM A system error has occurred.
363 result SetElementTextVerticalAlignment(int elementId, VerticalAlignment alignment);
366 * Sets the auto-link mask.
370 * @return An error code
371 * @param[in] elementId The element ID
372 * @param[in] mask The auto-link mask @n
373 * Multiple link types can be combined using bitwise OR operator (see Tizen::Base::Utility::LinkType). @n
374 * For more information, see <a href="../org.tizen.native.appprogramming/html/guide/ui/auto_link_detection.htm">AutoLink Detection</a>.
375 * @exception E_SUCCESS The method is successful.
376 * @exception E_INVALID_ARG A specified input parameter is invalid.
377 * @exception E_INVALID_OPERATION The specified element does not handle text.
378 * @exception E_SYSTEM A system error has occurred.
379 * @remarks When @c mask is set to @c 0, the auto-link detection is disabled.
380 * @see Tizen::Base::Utility::LinkType
382 result SetElementAutoLinkMask(int elementId, unsigned long mask);
386 // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
388 CustomItem(const CustomItem& rhs);
391 // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
393 CustomItem& operator =(const CustomItem& rhs);
396 }}} // Tizen::Ui::Controls
398 #endif // _FUI_CTRL_CUSTOM_ITEM_H_