From: Paul Wisbey Date: Thu, 28 May 2015 10:32:49 +0000 (+0100) Subject: TextField added to programming guide X-Git-Tag: accepted/tizen/common/20150529.134038~2^2 X-Git-Url: http://review.tizen.org/git/?p=platform%2Fcore%2Fuifw%2Fdali-toolkit.git;a=commitdiff_plain;h=9d994cff127d932aa64385aba479b015563f9929 TextField added to programming guide Change-Id: Ie18cd6207235b8b731fd593b0697745075b75f95 --- 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