1 #ifndef __DALI_TEXT_ACTOR_H__
2 #define __DALI_TEXT_ACTOR_H__
5 * Copyright (c) 2014 Samsung Electronics Co., Ltd.
7 * Licensed under the Apache License, Version 2.0 (the "License");
8 * you may not use this file except in compliance with the License.
9 * You may obtain a copy of the License at
11 * http://www.apache.org/licenses/LICENSE-2.0
13 * Unless required by applicable law or agreed to in writing, software
14 * distributed under the License is distributed on an "AS IS" BASIS,
15 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 * See the License for the specific language governing permissions and
17 * limitations under the License.
23 * @addtogroup CAPI_DALI_ACTORS_MODULE
31 #include <dali/public-api/actors/renderable-actor.h>
32 #include <dali/public-api/common/loading-state.h>
33 #include <dali/public-api/common/constants.h>
34 #include <dali/public-api/math/vector2.h>
35 #include <dali/public-api/text/text-style.h>
36 #include <dali/public-api/text/text.h>
38 namespace Dali DALI_IMPORT_API
43 namespace Internal DALI_INTERNAL
49 * @brief TextActor is a basic actor for displaying a text label
51 * By default the text actor always uses the natural size of the text when SetText is called,
52 * unless SetSize is called to override the size or size is animated to some other size.
53 * Natural size for TextActor is the same as the size returned by Font::MeasureText( string )
54 * using the font that the TextActor is using.
56 * By default CullFaceMode is set to CullNone to enable the TextActor to be viewed from all angles.
58 class DALI_IMPORT_API TextActor : public RenderableActor
62 typedef SignalV2< void (TextActor) > TextSignalV2; ///< Text available signal type
65 static const char* const SIGNAL_TEXT_LOADING_FINISHED; ///< name "text-loading-finished"
67 // Default Properties; additional to RenderableActor properties
68 static const Property::Index TEXT; ///< name "text" type STRING
69 static const Property::Index FONT; ///< name "font" type STRING
70 static const Property::Index FONT_STYLE; ///< name "font-style" type STRING
71 static const Property::Index OUTLINE_ENABLE; ///< name "outline-enable" type BOOLEAN
72 static const Property::Index OUTLINE_COLOR; ///< name "outline-color" type VECTOR4
73 static const Property::Index OUTLINE_THICKNESS_WIDTH; ///< name "outline-thickness-width" type VECTOR2
74 static const Property::Index SMOOTH_EDGE; ///< name "smooth-edge" type FLOAT
75 static const Property::Index GLOW_ENABLE; ///< name "glow-enable" type BOOLEAN
76 static const Property::Index GLOW_COLOR; ///< name "glow-color" type VECTOR4
77 static const Property::Index GLOW_INTENSITY; ///< name "glow-intensity" type FLOAT
78 static const Property::Index SHADOW_ENABLE; ///< name "shadow-enable" type BOOLEAN
79 static const Property::Index SHADOW_COLOR; ///< name "shadow-color" type VECTOR4
80 static const Property::Index SHADOW_OFFSET; ///< name "shadow-offset" type VECTOR2
81 static const Property::Index ITALICS_ANGLE; ///< name "italics-angle" type FLOAT
82 static const Property::Index UNDERLINE; ///< name "underline" type BOOLEAN
83 static const Property::Index WEIGHT; ///< name "weight" type INTEGER
84 static const Property::Index FONT_DETECTION_AUTOMATIC; ///< name "font-detection-automatic" type BOOLEAN
85 static const Property::Index GRADIENT_COLOR; ///< name "gradient-color" type VECTOR4
86 static const Property::Index GRADIENT_START_POINT; ///< name "gradient-start-point" type VECTOR2
87 static const Property::Index GRADIENT_END_POINT; ///< name "gradient-end-point" type VECTOR2
88 static const Property::Index SHADOW_SIZE; ///< name "shadow-size" type FLOAT
89 static const Property::Index TEXT_COLOR; ///< name "text-color" type VECTOR4
92 * @brief Create an uninitialized TextActor handle.
94 * This can be initialised with TextActor::New().
95 * Calling member functions with an uninitialized handle is not allowed.
100 * @brief Create a TextActor object with no text.
102 * @return A handle to a newly allocated Dali resource.
104 static TextActor New();
107 * @brief Create a TextActor object with LeftToRight text and font detection
109 * @param [in] text The text which will be displayed
110 * @return A handle to a newly allocated Dali resource.
112 static TextActor New(const std::string& text);
115 * @copydoc New(const std::string& text)
117 static TextActor New(const Text& text);
120 * @brief Create a TextActor object with LeftToRight text.
122 * @param [in] text The text which will be displayed
123 * @param [in] fontDetection Try to detect font in case text is not supported with current one.
124 * @return A handle to a newly allocated Dali resource.
126 static TextActor New(const std::string& text, bool fontDetection);
129 * @copydoc New(const std::string& text, bool fontDetection)
131 static TextActor New(const Text& text, bool fontDetection);
134 * @brief Create a TextActor object.
136 * @param [in] text The text which will be displayed
137 * @param [in] fontDetection Try to detect font in case text is not supported with current one.
138 * @param [in] isLeftToRight Text is displayed from left to right if true, otherwise from right to left.
139 * @return A handle to a newly allocated Dali resource.
141 static TextActor New(const std::string& text, bool fontDetection, bool isLeftToRight);
144 * @copydoc New(const std::string& text, bool fontDetection, bool isLeftToRight)
146 static TextActor New(const Text& text, bool fontDetection, bool isLeftToRight);
149 * @brief Create a TextActor object with LeftToRight text and font detection.
151 * @param [in] text The text which will be displayed
152 * @param [in] font The font which will be used for the text
153 * @return A handle to a newly allocated Dali resource.
155 static TextActor New(const std::string& text, Font font);
158 * @copydoc New(const std::string& text, Font font)
160 static TextActor New(const Text& text, Font font);
163 * @brief Create a TextActor object with LeftToRight text.
165 * @param [in] text The text which will be displayed
166 * @param [in] font The font which will be used for the text
167 * @param [in] fontDetection Try to detect font in case text is not supported with current one.
168 * @return A handle to a newly allocated Dali resource.
170 static TextActor New(const std::string& text, Font font, bool fontDetection);
173 * @copydoc New(const std::string& text, Font font, bool fontDetection)
175 static TextActor New(const Text& text, Font font, bool fontDetection);
178 * @brief Create a TextActor object.
180 * @param [in] text The text which will be displayed
181 * @param [in] font The font which will be used for the text
182 * @param [in] fontDetection Try to detect font in case text is not supported with current one.
183 * @param [in] isLeftToRight Text is displayed from left to right if true, otherwise from right to left.
184 * @return A handle to a newly allocated Dali resource.
186 static TextActor New(const std::string& text, Font font, bool fontDetection, bool isLeftToRight);
189 * @copydoc New(const std::string& text, Font font, bool fontDetection, bool isLeftToRight)
191 static TextActor New(const Text& text, Font font, bool fontDetection, bool isLeftToRight);
194 * @brief Create a TextActor object.
196 * @param [in] text The text which will be displayed
197 * @param [in] style The style which will be used for the text
198 * @param [in] fontDetection Try to detect font in case text is not supported with current one.
199 * @param [in] isLeftToRight Text is displayed from left to right if true, otherwise from right to left.
200 * @return A handle to a newly allocated Dali resource.
202 static TextActor New(const Text& text, const TextStyle& style, bool fontDetection, bool isLeftToRight);
205 * @brief Downcast an Object handle to TextActor.
207 * If handle points to a TextActor the downcast produces valid
208 * handle. If not the returned handle is left uninitialized.
209 * @param[in] handle to An object
210 * @return handle to a TextActor or an uninitialized handle
212 static TextActor DownCast( BaseHandle handle );
217 * This is non-virtual since derived Handle types must not contain data or virtual methods.
222 * @copydoc Dali::BaseHandle::operator=
224 using BaseHandle::operator=;
227 * @brief Get the text label displayed by the actor.
229 * @pre The text actor has been initialized.
230 * @return The text label
232 std::string GetText() const;
235 * @brief Set the text label displayed by the actor.
237 * @pre The text actor has been initialized.
238 * @param [in] text The new text label
240 void SetText(const std::string& text);
243 * @copydoc SetText(const std::string& text)
245 void SetText(const Text& text);
248 * @brief Set text to the natural size of the text string.
250 * After this method the text actor always uses the natural size of the text
251 * when SetText is called unless SetSize is called to override the size.
253 void SetToNaturalSize();
256 * @brief Get the font used to display the text label displayed by the actor.
258 * @pre The text actor has been initialized.
259 * @return The font currently in use
261 Font GetFont() const;
264 * @brief Set the font used to display the text label displayed by the actor.
266 * @pre The text actor has been initialized.
267 * @param [in] font The new font
269 void SetFont(Font& font);
271 // styling and effects
274 * @brief Set the gradient color.
276 * This is the color associated with the gradient end point.
277 * @param[in] color The gradient color (end-point color)
279 void SetGradientColor( const Vector4& color );
282 * @brief Get the gradient color.
284 * This is the color associated with the gradient end point.
285 * @return The gradient color (end-point color)
287 Vector4 GetGradientColor() const;
290 * @brief Set the gradient start point.
292 * This is a 2D position between the coordinate range:
293 * 0.0,0.0 (Left,Top) to 1.0,1.0 (Right,Bottom) within
294 * the outputted Text. Actor::COLOR will represent this point
296 * @param[in] position The relative position of the gradient start point.
298 void SetGradientStartPoint( const Vector2& position );
301 * @brief Get the gradient start point.
303 * @return The relative position of the gradient start point.
305 Vector2 GetGradientStartPoint() const;
308 * @brief Set the gradient end point.
310 * This is a 2D position between the coordinate range:
311 * 0.0,0.0 (Left,Top) to 1.0,1.0 (Right,Bottom) within
312 * the outputted Text. TextActor::GRADIENT_COLOR will represent
313 * this point in the gradient.
314 * @param[in] position The relative position of the gradient end point.
316 void SetGradientEndPoint( const Vector2& position );
319 * @brief Get the gradient end point.
321 * @return The relative position of the gradient end point.
323 Vector2 GetGradientEndPoint() const;
326 * @brief Sets text style.
328 * @param[in] style The text style.
330 void SetTextStyle( const TextStyle& style );
333 * @brief Retrieves a copy of the text style.
335 * @return The text style.
337 TextStyle GetTextStyle() const;
340 * @brief Set the text color.
342 * This is blended with the Actor color
343 * @param[in] color The text color (Default: WHITE)
345 void SetTextColor( const Vector4& color );
348 * @brief Get the text color.
350 * @return The text color.
352 Vector4 GetTextColor() const;
355 * @brief Set soft edge smoothing.
357 * @param[in] smoothEdge Specify the distance field value for the center of the text edge.
358 * 0 <= smoothEdge <= 1
360 void SetSmoothEdge( float smoothEdge = TextStyle::DEFAULT_SMOOTH_EDGE_DISTANCE_FIELD );
363 * @brief Set text outlining.
365 * @param[in] enable Set to true to enable text outlining.
366 * @param[in] color Outline color.
367 * @param[in] thickness Thickness of outline. The outline thickness is determined by two parameters.
368 * thickness[0] Specifies the distance field value for the center of the outline.
369 * thickness[1] Specifies the softness/width/anti-aliasing of the outlines inner edge.
370 * SetSmoothEdge() specifies the smoothness/anti-aliasing of the text outer edge.
371 * 0 <= smoothEdge[0] <= 1.
372 * 0 <= smoothEdge[1] <= 1.
374 void SetOutline( bool enable, const Vector4& color, const Vector2& thickness = TextStyle::DEFAULT_OUTLINE_THICKNESS );
377 * @brief Set text glow.
379 * @param[in] enable Set to true to enable text outer glow.
380 * @param[in] color Glow color.
381 * @param[in] intensity Determines the amount of glow around text.
382 * The edge of the text is at the value set with SetSmoothEdge().
383 * SetSmoothEdge() The distance field value at which the glow becomes fully transparent.
385 void SetGlow( bool enable, const Vector4& color, float intensity = TextStyle::DEFAULT_GLOW_INTENSITY );
388 * @brief Set text shadow.
390 * @param[in] enable Set to true to enable text drop shadow.
391 * @param[in] color Shadow color
392 * @param[in] offset Offset in pixels. To avoid cropping of the drop shadow limit the offset to PointSize / 3.5
393 * @param[in] size Size of shadow in pixels. 0 means the shadow is the same size as the text.
395 void SetShadow( bool enable, const Vector4& color, const Vector2& offset = TextStyle::DEFAULT_SHADOW_OFFSET,
396 float size = TextStyle::DEFAULT_SHADOW_SIZE );
399 * @brief Enable italics on the text actor, the text will be sheared by the given angle.
401 * @param[in] enabled True will enable italics, false disable it.
402 * @param[in] angle Italics angle in degrees.
404 void SetItalics( bool enabled, Degree angle = TextStyle::DEFAULT_ITALICS_ANGLE );
407 * @brief Enable italics on the text actor, the text will be sheared by the given angle.
409 * @param[in] enabled True will enable italics, false disable it.
410 * @param[in] angle Italics angle in radians.
412 void SetItalics( bool enabled, Radian angle );
415 * @brief Get text italics for the actor.
417 * @returns True if italics is enabled.
419 bool GetItalics() const;
422 * @brief Get text italics angle.
424 * @returns Angle as a Radian.
426 Radian GetItalicsAngle() const;
429 * @brief Set text underline.
431 * @param[in] enable Boolean indicating if the text should be underlined or not.
433 void SetUnderline( bool enable );
436 * @brief Get text underline.
438 * @return Boolean indicating if the text should be underlined or not.
440 bool GetUnderline() const;
443 * @brief Set text weight.
445 * @param weight Text weight.
447 void SetWeight( TextStyle::Weight weight );
450 * @brief Get text weight.
452 * @return Text weight.
454 TextStyle::Weight GetWeight() const;
457 * @brief Try to detect font in case text is not supported with current one.
459 * @param [in] value true or false
461 void SetFontDetectionAutomatic(bool value);
464 * @brief Query whether TextActor is using automatic font detection.
466 * @return true or false
468 bool IsFontDetectionAutomatic() const;
471 * @brief Query whether the font has been loaded and built.
473 * Should be used by the application to determine whether the font
474 * is ready to be queried for metrics
475 * @return The loading state, either Loading, Success or Failed.
477 LoadingState GetLoadingState() const;
480 * @brief Emitted when text loads successfully and is available for displaying, or when the loading fails.
482 * @return A signal object to Connect() with.
484 TextSignalV2& TextAvailableSignal();
486 public: // Not intended for use by Application developers
489 * @brief This constructor is used by Dali New() methods
491 * @param [in] actor A pointer to a newly allocated Dali resource
493 explicit DALI_INTERNAL TextActor(Internal::TextActor* actor);
501 #endif // __DALI_TEXT_ACTOR_H__