From: Paul Wisbey Date: Tue, 14 Apr 2015 15:12:08 +0000 (+0100) Subject: Text-related Programming guide updates X-Git-Tag: dali_1.0.39~16 X-Git-Url: http://review.tizen.org/git/?p=platform%2Fcore%2Fuifw%2Fdali-toolkit.git;a=commitdiff_plain;h=e7799b0ec7b39e083bbb99eebd896e2aa1c2f358 Text-related Programming guide updates Change-Id: I474917bd30af46ad58b389c5c8c3e4469578c606 --- diff --git a/dali-toolkit/internal/text/rendering/atlas/text-atlas-renderer.cpp b/dali-toolkit/internal/text/rendering/atlas/text-atlas-renderer.cpp index 7891391..b82b07b 100644 --- a/dali-toolkit/internal/text/rendering/atlas/text-atlas-renderer.cpp +++ b/dali-toolkit/internal/text/rendering/atlas/text-atlas-renderer.cpp @@ -21,6 +21,7 @@ // EXTERNAL INCLUDES #include #include +#include // INTERNAL INCLUDES #include @@ -722,4 +723,4 @@ AtlasRenderer::AtlasRenderer() AtlasRenderer::~AtlasRenderer() { delete mImpl; -} \ No newline at end of file +} diff --git a/docs/content/example-code/property-example.cpp b/docs/content/example-code/property-example.cpp index 35e7869..e0f40e6 100644 --- a/docs/content/example-code/property-example.cpp +++ b/docs/content/example-code/property-example.cpp @@ -101,7 +101,7 @@ class PropertyButtonsController: public ConnectionTracker } // Create the last selected button text view. - mTagText = Toolkit::TextView::New( "None selected" ); + mTagText = Toolkit::TextLabel::New( "None selected" ); mTagText.SetParentOrigin( ParentOrigin::BOTTOM_CENTER ); mTagText.SetAnchorPoint( AnchorPoint::BOTTOM_CENTER ); mTagText.SetPosition( Vector3( 0.0f, -30.0f, 0.0f ) ); @@ -121,14 +121,14 @@ class PropertyButtonsController: public ConnectionTracker // Property::Index index = button.GetPropertyIndex( TAG_PROPERTY_NAME ); valueText << "Selected: " << button.GetProperty< float >( mTagPropertyIndex ); - mTagText.SetText( valueText.str() ); + mTagText.SetProperty( TextLabel::Property::TEXT, valueText.str() ); return true; } private: - Toolkit::TextView mTagText; ///< A text label used to show the last button pressed. + Toolkit::TextLabel mTagText; ///< A text label used to show the last button pressed. Property::Index mTagPropertyIndex; ///< A cached property index of our custom tag property. }; diff --git a/docs/content/images/actors/Text-Actor.png b/docs/content/images/actors/Text-Actor.png deleted file mode 100644 index 6bba38e..0000000 Binary files a/docs/content/images/actors/Text-Actor.png and /dev/null differ diff --git a/docs/content/images/actors/Text-Label.png b/docs/content/images/actors/Text-Label.png new file mode 100644 index 0000000..cc2dc30 Binary files /dev/null and b/docs/content/images/actors/Text-Label.png differ diff --git a/docs/content/images/text-controls/HelloWorld-HeightForWidth.png b/docs/content/images/text-controls/HelloWorld-HeightForWidth.png new file mode 100644 index 0000000..915862c Binary files /dev/null and b/docs/content/images/text-controls/HelloWorld-HeightForWidth.png differ diff --git a/docs/content/images/text-controls/HelloWorld-NaturalSize.png b/docs/content/images/text-controls/HelloWorld-NaturalSize.png new file mode 100644 index 0000000..28d24d1 Binary files /dev/null and b/docs/content/images/text-controls/HelloWorld-NaturalSize.png differ diff --git a/docs/content/images/text-controls/PlainText.png b/docs/content/images/text-controls/PlainText.png new file mode 100644 index 0000000..5ef9ff1 Binary files /dev/null and b/docs/content/images/text-controls/PlainText.png differ diff --git a/docs/content/images/text-controls/RedText.png b/docs/content/images/text-controls/RedText.png new file mode 100644 index 0000000..f2fe9fe Binary files /dev/null and b/docs/content/images/text-controls/RedText.png differ diff --git a/docs/content/images/text-controls/TextWith1pxUnderline.png b/docs/content/images/text-controls/TextWith1pxUnderline.png new file mode 100644 index 0000000..082d19e Binary files /dev/null and b/docs/content/images/text-controls/TextWith1pxUnderline.png differ diff --git a/docs/content/images/text-controls/TextWithBiggerShadow.png b/docs/content/images/text-controls/TextWithBiggerShadow.png new file mode 100644 index 0000000..921f745 Binary files /dev/null and b/docs/content/images/text-controls/TextWithBiggerShadow.png differ diff --git a/docs/content/images/text-controls/TextWithColorShadow.png b/docs/content/images/text-controls/TextWithColorShadow.png new file mode 100644 index 0000000..a82635d Binary files /dev/null and b/docs/content/images/text-controls/TextWithColorShadow.png differ diff --git a/docs/content/images/text-controls/TextWithColorUnderline.png b/docs/content/images/text-controls/TextWithColorUnderline.png new file mode 100644 index 0000000..42ec4ff Binary files /dev/null and b/docs/content/images/text-controls/TextWithColorUnderline.png differ diff --git a/docs/content/images/text-controls/TextWithShadow.png b/docs/content/images/text-controls/TextWithShadow.png new file mode 100644 index 0000000..1cde8d2 Binary files /dev/null and b/docs/content/images/text-controls/TextWithShadow.png differ diff --git a/docs/content/images/text-controls/TextWithUnderline.png b/docs/content/images/text-controls/TextWithUnderline.png new file mode 100644 index 0000000..530920a Binary files /dev/null and b/docs/content/images/text-controls/TextWithUnderline.png differ diff --git a/docs/content/programming-guide/hello-world.h b/docs/content/programming-guide/hello-world.h index 8031d99..2065659 100644 --- a/docs/content/programming-guide/hello-world.h +++ b/docs/content/programming-guide/hello-world.h @@ -12,56 +12,71 @@ Let's take a look at the code for this test application.

Example code

\code -#include -using namespace Dali; +#include -/****************************************************** - * Demonstrates how to display "Hello World" on screen - ******************************************************/ +using namespace Dali; +using Dali::Toolkit::TextLabel; -class ExampleApp +// This example shows how to create and display Hello World! using a simple TextActor +// +class HelloWorldController : public ConnectionTracker { public: - ExampleApp(Application &app) - : mApp(app) + + HelloWorldController( Application& application ) + : mApplication( application ) { - // Connect to Dali::Application init signal. Do not make calls to Dali before this signal is received. - app.SignalInit().Connect(this, &ExampleApp::Create); + // Connect to the Application's Init signal + mApplication.InitSignal().Connect( this, &HelloWorldController::Create ); } - ~ExampleApp() + ~HelloWorldController() { - // Remove Hello World TextActor from stage - Stage::GetCurrent().Remove(mTextActor); + // Remove Hello World actor from stage + Stage::GetCurrent().Remove(mTextLabel); } -public: - - void Create(Application& app) + // The Init signal is received once (only) during the Application lifetime + void Create( Application& application ) { - // Initialize the actor - mTextActor = TextActor::New("Hello World"); + // Get a handle to the stage + Stage stage = Stage::GetCurrent(); + + mTextLabel = TextLabel::New( "Hello World" ); + mTextLabel.SetAnchorPoint( AnchorPoint::TOP_LEFT ); + stage.Add( mTextLabel ); - // Center the actor. Note: default anchor point is CENTER - mTextActor.SetParentOrigin(ParentOrigin::CENTER); + // Respond to a click anywhere on the stage + stage.GetRootLayer().TouchedSignal().Connect( this, &HelloWorldController::OnTouch ); + } - // Display the actor on the stage - Stage::GetCurrent().Add(mTextActor); + bool OnTouch( Actor actor, const TouchEvent& touch ) + { + // quit the application + mApplication.Quit(); + return true; } private: - Application& mApp; - TextActor mTextActor; + Application& mApplication; + TextLabel mTextLabel; }; -int -main(int argc, char **argv) +void RunTest( Application& application ) +{ + HelloWorldController test( application ); + + application.MainLoop(); +} + +// Entry point for Linux & Tizen applications +// +int main( int argc, char **argv ) { - Application daliApp(&argc, &argv); + Application application = Application::New( &argc, &argv ); - ExampleApp helloApp (daliApp); - daliApp.MainLoop(); + RunTest( application ); return 0; } @@ -85,10 +100,10 @@ main(int argc, char **argv) That's why we store the Actor's handle: \code ... - mTextActor = TextActor::New("Hello World"); + mTextLabel = TextLabel::New("Hello World"); ... \endcode - Even if the TextActor is removed from the stage, it will be kept alive through our reference.\n + Even if the TextLabel is removed from the stage, it will be kept alive through our reference.\n You can read more about implicit smart-pointer semantics in chapter \link handle-body-idiom Handle – body\endlink.

Main loop

@@ -107,6 +122,12 @@ main(int argc, char **argv) After running './hello' this should be visible on the screen: - \image html Text-Actor.png "Hello world example" + + + + +
+ \image html Text-Label.png "Hello world example" +
*/ diff --git a/docs/content/programming-guide/properties.h b/docs/content/programming-guide/properties.h index 8838e78..0a85d51 100644 --- a/docs/content/programming-guide/properties.h +++ b/docs/content/programming-guide/properties.h @@ -244,7 +244,7 @@ This is a basic example of a button defined in JSON by setting the default prope } }, "label-actor": { - "type": "TextView", + "type": "TextLabel", "text": "Normal" } } diff --git a/docs/content/programming-guide/script-hello.h b/docs/content/programming-guide/script-hello.h index 837e022..3bb5ece 100644 --- a/docs/content/programming-guide/script-hello.h +++ b/docs/content/programming-guide/script-hello.h @@ -6,19 +6,13 @@ * * @code * { - * "fonts": - * { - * "freesans": {"name": "FreeSans", "point-size": 12.0, "weight": "WEIGHT_REGULAR" } - * }, - * "actors": - * [ - * {"name":"text-actor", - * "type":"Text", - * "text":"Hello World", - * "font":"freesans", - * "parent-origin":"CENTER" - * } - * ] + * // a tree of actors + * "stage": [{ + * "name": "text-label", + * "type": "TextLabel", + * "text": "Hello World", + * "parent-origin": "CENTER" + * }] * } * @endcode * @@ -31,7 +25,7 @@ * * builder.LoadFromString(json_data); * - * Actor actor = builder.GetActor("text-actor"); + * Actor actor = builder.GetActor("text-label"); * * Stage::GetCurrent().Add(actor); * @endcode @@ -46,15 +40,15 @@ * daliscript hello-world.js * @endcode * - * The TextActor control to display Hello World can be constructed using Javascript dot notation accessing Dali Actor Properties. + * The TextLabel control to display Hello World can be constructed using Javascript dot notation accessing Dali Actor Properties. * * @code - * var textActor = Dali.TextActor(); + * var textLabel = Dali.TextLabel(); * - * textActor.text = "Hello World"; - * textActor.font = "FreeSans"; - * textActor.font-weight = "WEIGHT_REGULAR"; - * textActor.parent-origin = "CENTER"; + * textLabel.text = "Hello World"; + * textLabel.font-family = "FreeSans"; + * textLabel.font-style = "Regular"; + * textLabel.parent-origin = "CENTER"; * * Dali.Run(); * @endcode diff --git a/docs/content/programming-guide/size-negotiation.h b/docs/content/programming-guide/size-negotiation.h index 8259359..2f64d83 100644 --- a/docs/content/programming-guide/size-negotiation.h +++ b/docs/content/programming-guide/size-negotiation.h @@ -92,8 +92,7 @@ Dimension::WIDTH then there is a height-for-width dependency in effect. The clas is a text view that wraps its text. The following example snippet shows a text view that expands its width to the size of its parent, wraps its contents and then determines its height based on the width. @code -TextView text = TextView::New( "Example" ); -text.SetMultilinePolicy( SplitByWord ); +TextLabel text = TextLabel::New( "Example" ); text.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH ); text.SetResizePolicy( ResizePolicy::DIMENSION_DEPENDENCY, Dimension::HEIGHT ); @endcode @@ -140,11 +139,7 @@ content.SetFitHeight( 1 ); content.SetPadding( Padding( 20.0f, 20.0f, 20.0f, 0.0f ) ); // Text -Toolkit::TextView text = Toolkit::TextView::New(); -text.SetText( "Do you really want to quit?" ); -text.SetMultilinePolicy( Toolkit::TextView::SplitByWord ); -text.SetWidthExceedPolicy( Toolkit::TextView::Split ); -text.SetLineJustification( Toolkit::TextView::Left ); +Toolkit::TextLabel text = Toolkit::TextLabel::New( "Do you really want to quit?" ); text.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH ); text.SetResizePolicy( ResizePolicy::DIMENSION_DEPENDENCY, Dimension::HEIGHT ); @@ -174,9 +169,7 @@ checkBox.SetSize( Vector2( 48, 48 ) ); root.AddChild( checkBox, Toolkit::TableView::CellPosition( 0, 0 ) ); -Toolkit::TextView text2 = Toolkit::TextView::New(); -text2.SetText( "Don't show again" ); -text2.SetLineJustification( Toolkit::TextView::Left ); +Toolkit::TextLabel text2 = Toolkit::TextLabel::New( "Don't show again" ); text2.SetPadding( Padding( 20.0f, 0.0f, 0.0f, 10.0f ) ); root.AddChild( text2, Toolkit::TableView::CellPosition( 0, 1 ) ); diff --git a/docs/content/programming-guide/text-label.h b/docs/content/programming-guide/text-label.h index 35754de..24f8b1b 100644 --- a/docs/content/programming-guide/text-label.h +++ b/docs/content/programming-guide/text-label.h @@ -11,39 +11,33 @@ To display a TextLabel the TEXT property must be set using a UTF-8 string. \code TextLabel label = TextLabel::New(); label.SetProperty( TextLabel::Property::TEXT, "Hello World" ); +label.SetAnchorPoint( AnchorPoint::TOP_LEFT ); Stage::GetCurrent().Add( label ); \endcode The label must also be added to the stage, or to an actor which is on the stage.\n -In this example the text-label will be automatically given a natural size i.e. large enough to fit the text.\n -The position of the label on-screen is dependent on the parent-origin and anchor-point properties: +The position of the label on-screen is dependent on the parent-origin and anchor-point properties.\n - -
\image html TextLabelTopLeft.png - \image html TextLabelCenter.png -
(ParentOrigin::TOP_LEFT, AnchorPoint::TOP_LEFT) - (ParentOrigin::CENTER, AnchorPoint::CENTER) -
-\subsection fontselection Font Selection +\subsection fontSelection Font Selection By default TextLabel will automatically select a suitable font from the platform.\n Typically fonts do not support all scripts, for example Latin fonts often do not provide Arabic glyphs.\n Therefore you should expect TextLabel to select different fonts for each script. -Alternatively a font may be requested using eiter or all of FONT_FAMILY, FONT_STYLE, and POINT_SIZE properties: +Alternatively a font may be requested using either or all of FONT_FAMILY, FONT_STYLE, and POINT_SIZE properties: \code label.SetProperty( TextLabel::Property::FONT_FAMILY, "HelveticaNue" ); label.SetProperty( TextLabel::Property::FONT_STYLE, "Regular" ); @@ -51,16 +45,70 @@ label.SetProperty( TextLabel::Property::POINT_SIZE, 12.0f ); \endcode However the TextLabel will fall-back to using the default font, if the requested font does not support the required scripts. -\subsection fontselection Text Alignment +\subsection fontStyles Font Styles + +Setting a font size programmatically is not ideal for applications which support multiple screen resolutions etc.\n +A more flexible approach is to prepare various JSON stylesheets, and request a different style for each platform:\n + +\code +StyleManager styleManager = StyleManager::Get(); +styleManager.RequestThemeChange( "example-path/example.json" ); +\endcode + +To change the font for standard text labels, this JSON syntax can be used: + +\code +{ + "styles": + { + "textlabel": + { + "font-family":"Arial", + "font-style":"Regular", + "point-size":8 + } + } +} +\endcode + +However the same point-size is unlikely to be suitable for all labels in an application.\n +To set custom sizes simply set a "style name" for each case, and then provide a style override in JSON: + +\code + label.SetProperty( Control::Property::STYLE_NAME, "custom" ); +\endcode + +\code +{ + "styles": + { + "textlabel": + { + "font-family":"Arial", + "font-style":"Regular", + "point-size":8 + }, + + "custom": + { + "point-size":10 + } + } +} +\endcode + +In the example above, standard text labels will have point-size 8, and "custom" labels will have point-size 10.\n + +\subsection textAlignment Text Alignment Wrapping can be enabled using the MULTI_LINE property:\n \code label.SetProperty( TextLabel::Property::MULTI_LINE, true ); \endcode -The text can be either aligned to the start, end, or center of the available area: +The text can be either aligned horizontally to the beginning, end, or center of the available area: \code -label.SetProperty( TextLabel::Property::ALIGNMENT, "BEGIN" ); // "CENTER" or "END" +label.SetProperty( TextLabel::Property::HORIZONTAL_ALIGNMENT, "BEGIN" ); // "CENTER" or "END" \endcode @@ -105,4 +153,191 @@ label.SetProperty( TextLabel::Property::ALIGNMENT, "BEGIN" ); // "CENTER" or "EN
+The examples above assume that the TextLabel size greater than the minimum required.\n +The next section provides details about the other size related options. + +\subsection negotiatingSize Negotiating size + +\link size-negotiation Size negotiation \endlink is a layouting feature supported by UI controls such as TextLabel.\n +There are several resize policies which are commonly used with TextLabels.\n +The following examples show TextLabels actual size by setting a colored background, whilst the black area represents the size of the parent control:\n + +

Using natural size

+ +With a "natural" size TextLabel will be large enough to display the text without wrapping, and will not have extra space to align the text within.\n +Therefore in this example the same result would be displayed, regardless of the alignment or multi-line properties.\n + +\code +TextLabel label = TextLabel::New( "Hello World" ); +label.SetAnchorPoint( AnchorPoint::TOP_LEFT ); +label.SetResizePolicy( ResizePolicy::USE_NATURAL_SIZE, Dimension::ALL_DIMENSIONS ); +label.SetBackgroundColor( Color::BLUE ); +Stage::GetCurrent().Add( label ); +\endcode + + + + + +
+ \image html HelloWorld-NaturalSize.png +
+ +

Height-for-width negotiation

+ +To layout text labels vertically, a fixed (maximum) width should be provided by the parent control.\n +Each TextLabel will then report a desired height for the given width.\n +Here is an example of this behavior using TableView as the parent: + +\code +TableView parent = TableView::New( 3, 1 ); +parent.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH ); +parent.SetResizePolicy( ResizePolicy::USE_NATURAL_SIZE, Dimension::HEIGHT ); +parent.SetAnchorPoint( AnchorPoint::TOP_LEFT ); +Stage::GetCurrent().Add( parent ); + +TextLabel label = TextLabel::New( "Hello World" ); +label.SetAnchorPoint( AnchorPoint::TOP_LEFT ); +label.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH ); +label.SetResizePolicy( ResizePolicy::DIMENSION_DEPENDENCY, Dimension::HEIGHT ); +label.SetBackgroundColor( Color::BLUE ); +parent.AddChild( label, TableView::CellPosition( 0, 0 ) ); +parent.SetFitHeight( 0 ); + +label = TextLabel::New( "A Quick Brown Fox Jumps Over The Lazy Dog" ); +label.SetAnchorPoint( AnchorPoint::TOP_LEFT ); +label.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH ); +label.SetResizePolicy( ResizePolicy::DIMENSION_DEPENDENCY, Dimension::HEIGHT ); +label.SetBackgroundColor( Color::GREEN ); +label.SetProperty( TextLabel::Property::MULTI_LINE, true ); +parent.AddChild( label, TableView::CellPosition( 1, 0 ) ); +parent.SetFitHeight( 1 ); + +label = TextLabel::New( "لإعادة ترتيب الشاشات، يجب تغيير نوع العرض إلى شبكة قابلة للتخصيص." ); +label.SetAnchorPoint( AnchorPoint::TOP_LEFT ); +label.SetResizePolicy( ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH ); +label.SetResizePolicy( ResizePolicy::DIMENSION_DEPENDENCY, Dimension::HEIGHT ); +label.SetBackgroundColor( Color::BLUE ); +label.SetProperty( TextLabel::Property::MULTI_LINE, true ); +parent.AddChild( label, TableView::CellPosition( 2, 0 ) ); +parent.SetFitHeight( 2 ); +\endcode + + + + + +
+ \image html HelloWorld-HeightForWidth.png +
+ +Note that the "Hello World" text label (above) has been given the full width, not the natural width. + +\subsection textLabelDecorations TextLabel Decorations + +

Color

+ +To change the color of the text, the recommended way is to use the TEXT_COLOR property.\n +Note that unlike the Actor::COLOR property, this will not affect child Actors added to the TextLabel.\n + +\code +label.SetProperty( TextLabel::Property::TEXT, "Red Text" ); +label.SetProperty( TextLabel::Property::TEXT_COLOR, Color::RED ); +\endcode + + + + + +
+ \image html RedText.png +
+ +

Drop Shadow

+ +To add a drop-shadow to the text, simply set the SHADOW_OFFSET property with non-zero values.\n +The color can also be selected using the SHADOW_COLOR property.\n + +\code +stage.SetBackgroundColor( Color::BLUE ); + +label1.SetProperty( TextLabel::Property::TEXT, "Plain Text" ); + +label2.SetProperty( TextLabel::Property::TEXT, "Text with Shadow" ); +label2.SetProperty( TextLabel::Property::SHADOW_OFFSET, Vector2( 1.0f, 1.0f ) ); +label4.SetProperty( TextLabel::Property::SHADOW_COLOR, Color::BLACK ); + +label3.SetProperty( TextLabel::Property::TEXT, "Text with Bigger Shadow" ); +label3.SetProperty( TextLabel::Property::SHADOW_OFFSET, Vector2( 2.0f, 2.0f ) ); +label4.SetProperty( TextLabel::Property::SHADOW_COLOR, Color::BLACK ); + +label4.SetProperty( TextLabel::Property::TEXT, "Text with Color Shadow" ); +label4.SetProperty( TextLabel::Property::SHADOW_OFFSET, Vector2( 1.0f, 1.0f ) ); +label4.SetProperty( TextLabel::Property::SHADOW_COLOR, Color::RED ); +\endcode + + + + + + + + + + + + + + +
+ \image html PlainText.png +
+ \image html TextWithShadow.png +
+ \image html TextWithBiggerShadow.png +
+ \image html TextWithColorShadow.png +
+ +

Underline

+ +The text can be underlined by setting UNDERLINE_ENABLED.\n +The color can also be selected using the UNDERLINE_COLOR property.\n + +\code +label1.SetProperty( TextLabel::Property::TEXT, "Text with Underline" ); +label1.SetProperty( TextLabel::Property::UNDERLINE_ENABLED, true ); + +label2.SetProperty( TextLabel::Property::TEXT, "Text with Color Underline" ); +label2.SetProperty( TextLabel::Property::UNDERLINE_ENABLED, true ); +label2.SetProperty( TextLabel::Property::UNDERLINE_COLOR, Color::GREEN ); +\endcode + + + + + + + + +
+ \image html TextWithUnderline.png +
+ \image html TextWithColorUnderline.png +
+ +By default the underline height will be taken from the font metrics, however this can be overridden using the UNDERLINE_HEIGHT property: + +\code +label1.SetProperty( TextLabel::Property::UNDERLINE_HEIGHT, 1.0f ); +\endcode + + + + + +
+ \image html TextWith1pxUnderline.png +
+ */