From 9d994cff127d932aa64385aba479b015563f9929 Mon Sep 17 00:00:00 2001
From: Paul Wisbey
Date: Thu, 28 May 2015 11:32:49 +0100
Subject: [PATCH] TextField added to programming guide
Change-Id: Ie18cd6207235b8b731fd593b0697745075b75f95
---
docs/content/main.md | 2 +-
.../text-field.md | 146 +++++++++++++++++++++
.../text-label.md | 28 ++--
3 files changed, 161 insertions(+), 15 deletions(-)
create mode 100644 docs/content/shared-javascript-and-cpp-documentation/text-field.md
diff --git a/docs/content/main.md b/docs/content/main.md
index 1289468..69144db 100644
--- a/docs/content/main.md
+++ b/docs/content/main.md
@@ -58,7 +58,7 @@
### UI Controls
+ [Text Label](@ref text-label)
- + TextEntry
+ + [Text Field](@ref text-field)
+ Buttons
+ TableView
+ [Scroll View](@ref scroll-view)
diff --git a/docs/content/shared-javascript-and-cpp-documentation/text-field.md b/docs/content/shared-javascript-and-cpp-documentation/text-field.md
new file mode 100644
index 0000000..3706bfc
--- /dev/null
+++ b/docs/content/shared-javascript-and-cpp-documentation/text-field.md
@@ -0,0 +1,146 @@
+/**
+ *
+
+# Text Field {#text-field}
+
+## Overview
+
+The Dali::Toolkit::TextField is a control which provides a single-line editable text field.
+
+### Basic usage
+
+Before any text has been entered, the TextField can display some placeholder text.
+An alternative placeholder can be displayed when the TextField has keyboard focus.
+For example a TextField used to enter a username could initially show "Unknown Name", and then show "Enter Name." when the cursor is shown.
+
+~~~{.cpp}
+// C++
+
+TextField field = TextField::New();
+field.SetProperty( TextField::Property::PLACEHOLDER_TEXT, "Unnamed Name" );
+field.SetProperty( TextField::Property::PLACEHOLDER_TEXT_FOCUSED, "Enter Name." );
+
+Stage::GetCurrent().Add( field );
+~~~
+
+~~~{.js}
+// JavaScript
+
+var field = new dali.TextField();
+field.placeholderText = "Unnamed Name";
+field.placeholderTextFocused = "Enter Name.";
+
+dali.stage.add( field );
+~~~
+
+When the TextField is tapped, it will automatically gain the keyboard focus. Key events will then result in text being inserted, and the placeholder text will be removed.
+After text has been entered, it can be retrieved from the TEXT property.
+
+~~~{.cpp}
+// C++
+
+Property::Value fieldText = field.GetProperty( TextField::Property::TEXT );
+std::cout << "Received text: " << fieldText.Get< std::string >() << std::endl;
+~~~
+
+~~~{.js}
+// JavaScript
+
+console.log( field.text );
+~~~
+
+### Font Selection
+
+TextField will automatically select a suitable fonts, in the same was as TextLabel.
+The preferred font can also be selected from a JSON stylesheet:
+
+~~~{.json}
+{
+ "styles":
+ {
+ "textfield":
+ {
+ "font-family":"Arial",
+ "font-style":"Regular",
+ "point-size":8
+ }
+ }
+}
+~~~
+
+### Text Alignment
+
+TextField displays a single-line of text, which will scroll if there is not enough room for the text displayed.
+If there is enough room, then the text can be aligned horizontally to the beginning, end, or center of the available area:
+
+~~~{.cpp}
+// C++
+
+field.SetProperty( TextField::Property::HORIZONTAL_ALIGNMENT, "BEGIN" ); // "CENTER" or "END"
+~~~
+
+~~~{.js}
+// JavaScript
+
+field.HorizontalAlignment = "BEGIN"; // "CENTER" or "END"
+~~~
+
+### TextField Decorations
+
+#### Color
+
+To change the color of the text, the recommended way is to use the TEXT_COLOR property.
+An alternative color can be used for placeholder text by setting PLACEHOLDER_TEXT_COLOR.
+Note that unlike the Actor::COLOR property, these properties will not affect child Actors added to the TextField.
+
+~~~{.cpp}
+// C++
+field.SetProperty( TextField::Property::TEXT_COLOR, Color::CYAN );
+field.SetProperty( TextField::Property::PLACEHOLDER_TEXT_COLOR, Color::BLACK );
+~~~
+
+~~~{.js}
+// JavaScript
+
+field.textColor = dali.COLOR_CYAN;
+field.placeholderTextColor = dali.COLOR_BLACK;
+~~~
+
+### Text Field Properties
+
+ Name (JavaScript) | Name (C++) | Type | Writable | Animatable
+-----------------------------------|--------------------------------------|--------------|--------------|-----------
+ renderingBackend | RENDERING_BACKEND | INTEGER | O | X
+ text | TEXT | STRING | O | X
+ placeholderText | PLACEHOLDER_TEXT | STRING | O | X
+ placeholderTextFocused | PLACEHOLDER_TEXT_FOCUSED | STRING | O | X
+ fontFamily | FONT_FAMILY | STRING | O | X
+ fontStyle | FONT_STYLE | STRING | O | X
+ pointSize | POINT_SIZE | FLOAT | O | X
+ maxLength | MAX_LENGTH | INTEGER | O | X
+ exceedPolicy | EXCEED_POLICY | INTEGER | O | X
+ horizontalAlignment | HORIZONTAL_ALIGNMENT | STRING | O | X
+ verticalAlignment | VERTICAL_ALIGNMENT | STRING | O | X
+ textColor | TEXT_COLOR | VECTOR4 | O | X
+ shadowOffset | SHADOW_OFFSET | VECTOR2 | O | X
+ shadowColor | SHADOW_COLOR | VECTOR4 | O | X
+ primaryCursorColor | PRIMARY_CURSOR_COLOR | VECTOR4 | O | X
+ secondaryCursorColor | SECONDARY_CURSOR_COLOR | VECTOR4 | O | X
+ enableCursorBlink | ENABLE_CURSOR_BLINK | BOOLEAN | O | X
+ cursorBlinkInterval | CURSOR_BLINK_INTERVAL | FLOAT | O | X
+ cursorBlinkDuration | CURSOR_BLINK_DURATION | FLOAT | O | X
+ grabHandleImage | GRAB_HANDLE_IMAGE | STRING | O | X
+ grabHandlePressedImage | GRAB_HANDLE_PRESSED_IMAGE | STRING | O | X
+ scrollThreshold | SCROLL_THRESHOLD | FLOAT | O | X
+ scrollSpreed | SCROLL_SPEED | FLOAT | O | X
+ selectionHandleImageLeft | SELECTION_HANDLE_IMAGE_LEFT | STRING | O | X
+ selectionHandleImageRight | SELECTION_HANDLE_IMAGE_RIGHT | STRING | O | X
+ selectionHandlePressedImageLeft | SELECTION_HANDLE_PRESSED_IMAGE_LEFT | STRING | O | X
+ selectionHandlePressedImageRight | SELECTION_HANDLE_PRESSED_IMAGE_RIGHT | STRING | O | X
+ selectionHighlightColor | SELECTION_HIGHLIGHT_COLOR | VECTOR4 | O | X
+ decorationBoundingBox | DECORATION_BOUNDING_BOX | RECTANGLE | O | X
+ inputMethodSettings | INPUT_METHOD_SETTINGS | MAP | O | X
+
+@class TextField
+
+*/
diff --git a/docs/content/shared-javascript-and-cpp-documentation/text-label.md b/docs/content/shared-javascript-and-cpp-documentation/text-label.md
index 908fedd..b6719ed 100644
--- a/docs/content/shared-javascript-and-cpp-documentation/text-label.md
+++ b/docs/content/shared-javascript-and-cpp-documentation/text-label.md
@@ -398,20 +398,20 @@ label1.underlineHeight = 1;
Name (JavaScript) | Name (C++) | Type | Writable | Animatable
---------------------|---------------------|--------------|--------------|-----------
- renderingBackend | RENDERING_BACKEND | INTEGER | ✔ | ✘
- text | TEXT | STRING | ✔ | ✘
- fontFamily | FONT_FAMILY | STRING | ✔ | ✘
- fontStyle | FONT_STYLE | STRING | ✔ | ✘
- pointSize | POINT_SIZE | FLOAT | ✔ | ✘
- multiLine | MULTI_LINE | BOOLEAN | ✔ | ✘
- horizontalAlignment | HORIZONTAL_ALIGNMENT| STRING | ✔ | ✘
- verticalAlignment | VERTICAL_ALIGNMENT | STRING | ✔ | ✘
- textColor | TEXT_COLOR | VECTOR4 | ✔ | ✘
- shadowOffset | SHADOW_OFFSET | VECTOR2 | ✔ | ✘
- shadowColor | SHADOW_COLOR | VECTOR4 | ✔ | ✘
- underlineEnabled | UNDERLINE_ENABLED | BOOLEAN | ✔ | ✘
- underlineColor | UNDERLINE_COLOR | VECTOR4 | ✔ | ✘
- underlineHeight | UNDERLINE_HEIGHT | FLOAT | ✔ | ✘
+ renderingBackend | RENDERING_BACKEND | INTEGER | O | X
+ text | TEXT | STRING | O | X
+ fontFamily | FONT_FAMILY | STRING | O | X
+ fontStyle | FONT_STYLE | STRING | O | X
+ pointSize | POINT_SIZE | FLOAT | O | X
+ multiLine | MULTI_LINE | BOOLEAN | O | X
+ horizontalAlignment | HORIZONTAL_ALIGNMENT| STRING | O | X
+ verticalAlignment | VERTICAL_ALIGNMENT | STRING | O | X
+ textColor | TEXT_COLOR | VECTOR4 | O | X
+ shadowOffset | SHADOW_OFFSET | VECTOR2 | O | X
+ shadowColor | SHADOW_COLOR | VECTOR4 | O | X
+ underlineEnabled | UNDERLINE_ENABLED | BOOLEAN | O | X
+ underlineColor | UNDERLINE_COLOR | VECTOR4 | O | X
+ underlineHeight | UNDERLINE_HEIGHT | FLOAT | O | X
--
2.7.4