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.
26 #include <dali/public-api/actors/renderable-actor.h>
27 #include <dali/public-api/common/loading-state.h>
28 #include <dali/public-api/common/constants.h>
29 #include <dali/public-api/math/vector2.h>
30 #include <dali/public-api/text/text-style.h>
31 #include <dali/public-api/text/text.h>
36 struct TextActorParameters;
39 namespace Internal DALI_INTERNAL
45 * @brief TextActor is a basic actor for displaying a text label
47 * By default the text actor always uses the natural size of the text when SetText is called,
48 * unless SetSize is called to override the size or size is animated to some other size.
49 * Natural size for TextActor is the same as the size returned by Font::MeasureText( string )
50 * using the font that the TextActor is using.
52 * By default CullFaceMode is set to CullNone to enable the TextActor to be viewed from all angles.
55 * | %Signal Name | Method |
56 * |-----------------------|----------------------------|
57 * | text-loading-finished | @ref TextAvailableSignal() |
59 class DALI_IMPORT_API TextActor : public RenderableActor
64 * @brief An enumeration of properties belonging to the TextActor class.
65 * Properties additional to RenderableActor.
71 Text = DEFAULT_DERIVED_ACTOR_PROPERTY_START_INDEX, ///< name "text" type String
72 Font, ///< name "font" type String
73 FontStyle, ///< name "font-style" type String
74 OutlineEnable, ///< name "outline-enable" type Boolean
75 OutlineColor, ///< name "outline-color" type Vector4
76 OutlineThicknessWidth, ///< name "outline-thickness-width" type Vector2
77 SmoothEdge, ///< name "smooth-edge" type Float
78 GlowEnable, ///< name "glow-enable" type Boolean
79 GlowColor, ///< name "glow-color" type Vector4
80 GlowIntensity, ///< name "glow-intensity" type Float
81 ShadowEnable, ///< name "shadow-enable" type Boolean
82 ShadowColor, ///< name "shadow-color" type Vector4
83 ShadowOffset, ///< name "shadow-offset" type Vector2
84 ItalicsAngle, ///< name "italics-angle" type Float
85 Underline, ///< name "underline" type Boolean
86 Weight, ///< name "weight" type Integer
87 FontDetectionAutomatic, ///< name "font-detection-automatic" type Boolean
88 GradientColor, ///< name "gradient-color" type Vector4
89 GradientStartPoint, ///< name "gradient-start-point" type Vector2
90 GradientEndPoint, ///< name "gradient-end-point" type Vector2
91 ShadowSize, ///< name "shadow-size" type Float
92 TextColor, ///< name "text-color" type Vector4
96 typedef Signal< void (TextActor) > TextSignalType; ///< Text available signal type
99 * @brief Create an uninitialized TextActor handle.
101 * This can be initialised with TextActor::New().
102 * Calling member functions with an uninitialized handle is not allowed.
107 * @brief Create a TextActor object with no text.
109 * @return A handle to a newly allocated Dali resource.
111 static TextActor New();
114 * @brief Create a TextActor object with text, a default style and font detection.
116 * @param[in] text The text which will be displayed
118 static TextActor New( const Text& text );
121 * @brief Create a TextActor object with text.
123 * The style and whether to automatically detect the font could be set in the parameters.
125 * @param[in] text The text which will be displayed
126 * @param[in] parameters Text parameters.
128 static TextActor New( const Text& text, const TextActorParameters& parameters );
131 * @brief Downcast an Object handle to TextActor.
133 * If handle points to a TextActor the downcast produces valid
134 * handle. If not the returned handle is left uninitialized.
135 * @param[in] handle to An object
136 * @return handle to a TextActor or an uninitialized handle
138 static TextActor DownCast( BaseHandle handle );
143 * This is non-virtual since derived Handle types must not contain data or virtual methods.
148 * @brief Copy constructor
150 * @param [in] copy The actor to copy.
152 TextActor(const TextActor& copy);
155 * @brief Assignment operator
157 * @param [in] rhs The actor to copy.
159 TextActor& operator=(const TextActor& rhs);
162 * @brief Get the text label displayed by the actor.
164 * @pre The text actor has been initialized.
165 * @return The text label
167 std::string GetText() const;
170 * @brief Set the text label displayed by the actor.
172 * @pre The text actor has been initialized.
173 * @param [in] text The new text label
175 void SetText(const Text& text);
178 * @brief Set text to the natural size of the text string.
180 * After this method the text actor always uses the natural size of the text
181 * when SetText is called unless SetSize is called to override the size.
183 void SetToNaturalSize();
186 * @brief Get the font used to display the text label displayed by the actor.
188 * @pre The text actor has been initialized.
189 * @return The font currently in use
191 Font GetFont() const;
194 * @brief Set the font used to display the text label displayed by the actor.
196 * @pre The text actor has been initialized.
197 * @param [in] font The new font
199 void SetFont(Font& font);
201 // styling and effects
204 * @brief Set the gradient color.
206 * This is the color associated with the gradient end point.
207 * @param[in] color The gradient color (end-point color)
209 void SetGradientColor( const Vector4& color );
212 * @brief Get the gradient color.
214 * This is the color associated with the gradient end point.
215 * @return The gradient color (end-point color)
217 Vector4 GetGradientColor() const;
220 * @brief Set the gradient start point.
222 * This is a 2D position between the coordinate range:
223 * 0.0,0.0 (Left,Top) to 1.0,1.0 (Right,Bottom) within
224 * the outputted Text. Actor::COLOR will represent this point
226 * @param[in] position The relative position of the gradient start point.
228 void SetGradientStartPoint( const Vector2& position );
231 * @brief Get the gradient start point.
233 * @return The relative position of the gradient start point.
235 Vector2 GetGradientStartPoint() const;
238 * @brief Set the gradient end point.
240 * This is a 2D position between the coordinate range:
241 * 0.0,0.0 (Left,Top) to 1.0,1.0 (Right,Bottom) within
242 * the outputted Text. TextActor::GRADIENT_COLOR will represent
243 * this point in the gradient.
244 * @param[in] position The relative position of the gradient end point.
246 void SetGradientEndPoint( const Vector2& position );
249 * @brief Get the gradient end point.
251 * @return The relative position of the gradient end point.
253 Vector2 GetGradientEndPoint() const;
256 * @brief Sets text style.
258 * @param[in] style The text style.
260 void SetTextStyle( const TextStyle& style );
263 * @brief Retrieves a copy of the text style.
265 * @return The text style.
267 TextStyle GetTextStyle() const;
270 * @brief Set the text color.
272 * This is blended with the Actor color
273 * @param[in] color The text color (Default: WHITE)
275 void SetTextColor( const Vector4& color );
278 * @brief Get the text color.
280 * @return The text color.
282 Vector4 GetTextColor() const;
285 * @brief Set soft edge smoothing.
287 * @param[in] smoothEdge Specify the distance field value for the center of the text edge.
288 * 0 <= smoothEdge <= 1
290 void SetSmoothEdge( float smoothEdge = TextStyle::DEFAULT_SMOOTH_EDGE_DISTANCE_FIELD );
293 * @brief Set text outlining.
295 * @param[in] enable Set to true to enable text outlining.
296 * @param[in] color Outline color.
297 * @param[in] thickness Thickness of outline. The outline thickness is determined by two parameters.
298 * thickness[0] Specifies the distance field value for the center of the outline.
299 * thickness[1] Specifies the softness/width/anti-aliasing of the outlines inner edge.
300 * SetSmoothEdge() specifies the smoothness/anti-aliasing of the text outer edge.
301 * 0 <= smoothEdge[0] <= 1.
302 * 0 <= smoothEdge[1] <= 1.
304 void SetOutline( bool enable, const Vector4& color, const Vector2& thickness = TextStyle::DEFAULT_OUTLINE_THICKNESS );
307 * @brief Set text glow.
309 * @param[in] enable Set to true to enable text outer glow.
310 * @param[in] color Glow color.
311 * @param[in] intensity Determines the amount of glow around text.
312 * The edge of the text is at the value set with SetSmoothEdge().
313 * SetSmoothEdge() The distance field value at which the glow becomes fully transparent.
315 void SetGlow( bool enable, const Vector4& color, float intensity = TextStyle::DEFAULT_GLOW_INTENSITY );
318 * @brief Set text shadow.
320 * @param[in] enable Set to true to enable text drop shadow.
321 * @param[in] color Shadow color
322 * @param[in] offset Offset in pixels. To avoid cropping of the drop shadow limit the offset to PointSize / 3.5
323 * @param[in] size Size of shadow in pixels. 0 means the shadow is the same size as the text.
325 void SetShadow( bool enable, const Vector4& color, const Vector2& offset = TextStyle::DEFAULT_SHADOW_OFFSET,
326 float size = TextStyle::DEFAULT_SHADOW_SIZE );
329 * @brief Enable italics on the text actor, the text will be sheared by the given angle.
331 * @param[in] enabled True will enable italics, false disable it.
332 * @param[in] angle Italics angle in degrees.
334 void SetItalics( bool enabled, Degree angle = TextStyle::DEFAULT_ITALICS_ANGLE );
337 * @brief Enable italics on the text actor, the text will be sheared by the given angle.
339 * @param[in] enabled True will enable italics, false disable it.
340 * @param[in] angle Italics angle in radians.
342 void SetItalics( bool enabled, Radian angle );
345 * @brief Get text italics for the actor.
347 * @returns True if italics is enabled.
349 bool GetItalics() const;
352 * @brief Get text italics angle.
354 * @returns Angle as a Radian.
356 Radian GetItalicsAngle() const;
359 * @brief Set text underline.
361 * @param[in] enable Boolean indicating if the text should be underlined or not.
363 void SetUnderline( bool enable );
366 * @brief Get text underline.
368 * @return Boolean indicating if the text should be underlined or not.
370 bool GetUnderline() const;
373 * @brief Set text weight.
375 * @param weight Text weight.
377 void SetWeight( TextStyle::Weight weight );
380 * @brief Get text weight.
382 * @return Text weight.
384 TextStyle::Weight GetWeight() const;
387 * @brief Try to detect font in case text is not supported with current one.
389 * @param [in] value true or false
391 void SetFontDetectionAutomatic(bool value);
394 * @brief Query whether TextActor is using automatic font detection.
396 * @return true or false
398 bool IsFontDetectionAutomatic() const;
401 * @brief Query whether the font has been loaded and built.
403 * Should be used by the application to determine whether the font
404 * is ready to be queried for metrics
405 * @return The loading state, either Loading, Success or Failed.
407 LoadingState GetLoadingState() const;
410 * @brief Emitted when text loads successfully and is available for displaying, or when the loading fails.
412 * @return A signal object to Connect() with.
414 TextSignalType& TextAvailableSignal();
416 public: // Not intended for use by Application developers
419 * @brief This constructor is used by Dali New() methods
421 * @param [in] actor A pointer to a newly allocated Dali resource
423 explicit DALI_INTERNAL TextActor(Internal::TextActor* actor);
428 #endif // __DALI_TEXT_ACTOR_H__