From 62548206943a2b088f41319de7bbab0643a7e4b0 Mon Sep 17 00:00:00 2001
From: Jerome Pasion <jerome.pasion@digia.com>
Date: Thu, 7 Mar 2013 18:25:39 +0100
Subject: [PATCH] Doc: Edited TextField documentation
-reworded some sentences.
Change-Id: I8bce735c4fdeff0f542e5ce5d0ad424b233f9a65
Reviewed-by: Jens Bache-Wiig <jens.bache-wiig@digia.com>
---
src/controls/TextField.qml | 189 +++++++++++++++++++++----------------
1 file changed, 109 insertions(+), 80 deletions(-)
diff --git a/src/controls/TextField.qml b/src/controls/TextField.qml
index 55d90fa76..f88320d1c 100644
--- a/src/controls/TextField.qml
+++ b/src/controls/TextField.qml
@@ -48,12 +48,12 @@ import "Styles/Settings.js" as Settings
\qmltype TextField
\inqmlmodule QtQuick.Controls 1.0
\ingroup controls
- \brief TextField displays a single line of editable plain text.
+ \brief Displays a single line of editable plain text.
- TextField is used to accept a line of text input. Input constraints
- can be placed on a TextField item (for example, through a \l validator or \l inputMask),
- and setting \l echoMode to an appropriate value enables TextField to be used for
- a password input field.
+ TextField is used to accept a line of text input. Input constraints can be
+ placed on a TextField item (for example, through a \l validator or \l
+ inputMask). Setting \l echoMode to an appropriate value enables
+ TextField to be used for a password input field.
\sa TextArea, TextInput
*/
@@ -64,12 +64,16 @@ Control {
/*!
\qmlproperty bool TextField::acceptableInput
- This property is always true unless a validator or input mask has been set.
- If a validator or input mask has been set, this property will only be true
- if the current text is acceptable to the validator or input mask as a final
- string (not as an intermediate string).
+ Returns \c true if the text field contains acceptable
+ text.
- \sa validator, inputMask
+ If a validator or input mask was set, this property will return \c
+ true if the current text satisfies the validator or mask as
+ a final string (not as an intermediate string).
+
+ The default value is \c true.
+
+ \sa validator, inputMask, accepted
*/
readonly property alias acceptableInput: textInput.acceptableInput // read only
@@ -77,52 +81,55 @@ Control {
/*!
\qmlproperty bool TextField::activeFocusOnPress
- Whether the TextField should gain active focus on a mouse press. By default this is
- set to \c true.
+ This property is set to \c true if the TextField should gain active
+ focus on a mouse press.
+
+ The default value is \c true.
*/
property alias activeFocusOnPress: textInput.activeFocusOnPress
/*!
\qmlproperty bool TextField::canPaste
- Returns true if the TextField is writable and the content of the clipboard is
- suitable for pasting into the TextField.
+ Returns \c true if the TextField is writable and the content of the
+ clipboard is suitable for pasting into the TextField.
*/
readonly property alias canPaste: textInput.canPaste
/*!
\qmlproperty bool TextField::canRedo
- Returns true if the TextField is writable and there are \l {undo}{undone}
- operations that can be redone.
+ Returns \c true if the TextField is writable and there are \l
+ {undo}{undone} operations that can be redone.
*/
readonly property alias canRedo: textInput.canRedo
/*!
\qmlproperty bool TextField::canUndo
- Returns true if the TextField is writable and there are previous operations
- that can be undone.
+ Returns \c true if the TextField is writable and there are previous
+ operations that can be undone.
*/
readonly property alias canUndo: textInput.canUndo
/*!
\qmlproperty color TextField::textColor
- The text color.
+ This property holds the text color.
*/
property alias textColor: textInput.color
/*!
\qmlproperty int TextField::cursorPosition
- The position of the cursor in the TextField.
+
+ This property holds the position of the cursor in the TextField.
*/
property alias cursorPosition: textInput.cursorPosition
/*!
\qmlproperty string TextField::displayText
- This is the text displayed in the TextField.
+ This property holds the text displayed in the TextField.
If \l echoMode is set to TextInput::Normal, this holds the
same value as the TextField::text property. Otherwise,
@@ -134,13 +141,16 @@ Control {
/*!
\qmlproperty enumeration TextField::echoMode
- Specifies how the text should be displayed in the TextField.
+ Specifies how the text should be displayed in the
+ TextField.
+
+ The possible modes are:
\list
\li TextInput.Normal - Displays the text as it is. (Default)
\li TextInput.Password - Displays asterisks instead of characters.
\li TextInput.NoEcho - Displays nothing.
- \li TextInput.PasswordEchoOnEdit - Displays characters as they are entered
- while editing, otherwise displays asterisks.
+ \li TextInput.PasswordEchoOnEdit - Displays characters as they are
+ entered while editing, otherwise displays asterisks.
\endlist
*/
property alias echoMode: textInput.echoMode
@@ -148,7 +158,7 @@ Control {
/*!
\qmlproperty font TextField::font
- The font of the TextField.
+ Sets the font of the TextField.
*/
property alias font: textInput.font
@@ -157,25 +167,34 @@ Control {
Sets the alignment of the text within the TextField item's width.
- By default, the horizontal text alignment follows the natural alignment of the text,
- for example text that is read from left to right will be aligned to the left.
+ By default, the horizontal text alignment follows the natural alignment
+ of the text, for example text that is read from left to right will be
+ aligned to the left.
- The valid values for \c horizontalAlignment are \c TextInput.AlignLeft, \c TextInput.AlignRight and
- \c TextInput.AlignHCenter.
+ The possible alignment values are:
+ \list
+ \li TextInput.AlignLeft
+ \li TextInput.AlignRight
+ \li TextInput.AlignHCenter
+ \endlist
- When using the attached property LayoutMirroring::enabled to mirror application
- layouts, the horizontal alignment of text will also be mirrored. However, the property
- \c horizontalAlignment will remain unchanged. To query the effective horizontal alignment
- of TextField, use the read-only property \c effectiveHorizontalAlignment.
+ When using the attached property, LayoutMirroring::enabled, to mirror
+ application layouts, the horizontal alignment of text will also be
+ mirrored. However, the property \c horizontalAlignment will remain
+ unchanged. To query the effective horizontal alignment of TextField, use
+ the read-only property \c effectiveHorizontalAlignment.
*/
property alias horizontalAlignment: textInput.horizontalAlignment
/*!
\qmlproperty enumeration TextField::effectiveHorizontalAlignment
- Gets the effective horizontal alignment of the text within the TextField item's width.
+ Gets the effective horizontal alignment of the text within the TextField
+ item's width.
+
+ \l horizontalAlignment contains the default horizontal alignment.
- To set/get the default horizontal alignment of TextField, use the property \c horizontalAlignment.
+ \sa horizontalAlignment
*/
readonly property alias effectiveHorizontalAlignment: textInput.effectiveHorizontalAlignment
@@ -185,17 +204,21 @@ Control {
Sets the alignment of the text within the TextField item's height.
- The valid valid values for \c verticalAlignment are \c TextInput.AlignTop,
- \c TextInput.AlignBottom \c TextInput.AlignVCenter (default).
+ The possible alignment values are
+ \list
+ \li TextInput.AlignTop
+ \li TextInput.AlignBottom
+ \li TextInput.AlignVCenter (default).
+ \endlist
*/
property alias verticalAlignment: textInput.verticalAlignment
/*!
\qmlproperty string TextField::inputMask
- Allows you to set an input mask on the TextField, restricting the allowable
- text inputs. See QLineEdit::inputMask for further details, as the exact
- same mask strings are used by TextField.
+ Sets an input mask on the TextField, restricting the allowable text
+ inputs. See QLineEdit::inputMask for further details, as the exact same
+ mask strings are used by TextField.
\sa acceptableInput, validator
*/
@@ -204,12 +227,13 @@ Control {
/*!
\qmlproperty enumeration TextField::inputMethodHints
- Provides hints to the input method about the expected content of the text field and how it
- should operate.
+ Provides hints to the input method about the expected content of the
+ text field and how it should operate.
- The value is a bit-wise combination of flags, or Qt.ImhNone if no hints are set.
+ The value is a bit-wise combination of flags, or \c Qt.ImhNone if no
+ hints are set.
- The default value is Qt.ImhNone.
+ The default value is \c Qt.ImhNone.
Flags that alter behavior are:
@@ -223,7 +247,7 @@ Control {
\li Qt.ImhPreferNumbers - Numbers are preferred (but not required).
\li Qt.ImhPreferUppercase - Upper case letters are preferred (but not required).
\li Qt.ImhPreferLowercase - Lower case letters are preferred (but not required).
- \li Qt.ImhNoPredictiveText - Do not use predictive text (i.e. dictionary lookup) while typing.
+ \li Qt.ImhNoPredictiveText - Do not use predictive text (for example, dictionary lookup) while typing.
\li Qt.ImhDate - The text editor functions as a date field.
\li Qt.ImhTime - The text editor functions as a time field.
@@ -242,7 +266,6 @@ Control {
\endlist
Masks:
-
\list
\li Qt.ImhExclusiveInputMask - This mask yields nonzero if any of the exclusive flags are used.
\endlist
@@ -254,17 +277,21 @@ Control {
Returns the total number of characters in the TextField item.
- If the TextField has an inputMask the length will include mask characters and may differ
- from the length of the string returned by the \l text property.
+ If the TextField has an input mask, the length will include mask
+ characters and may differ from the length of the string returned by the
+ \l text property.
- This property can be faster than querying the length the \l text property as it doesn't
- require any copying or conversion of the TextField's internal string data.
+ This property can be faster than querying the length the \l text
+ property as it doesn't require any copying or conversion of the
+ TextField's internal string data.
*/
readonly property alias length: textInput.length
/*!
\qmlproperty int TextField::maximumLength
- The maximum permitted length of the text in the TextField.
+
+ This property holds the maximum permitted length of the text in the
+ TextField.
If the text is too long, it is truncated at the limit.
*/
@@ -273,36 +300,35 @@ Control {
/*!
\qmlproperty string TextField::placeholderText
- The text that is shown in the text field when the text field is empty
- and has no focus.
+ This property contains the text that is shown in the text field when the
+ text field is empty and has no focus.
*/
property alias placeholderText: placeholderTextComponent.text
/*!
\qmlproperty bool TextField::readOnly
- Sets whether user input can modify the contents of the TextField.
- The difference from a disabled text field is that it will appear
- to be active and text can be selected and copied.
+ Sets whether user input can modify the contents of the TextField. Read-
+ only is different from a disabled text field in that the text field will
+ appear to be active and text can still be selected and copied.
- If readOnly is set to true, then user input will not affect the text
- property. Any bindings or attempts to set the text property will still
- work.
+ If readOnly is set to \c true, then user input will not affect the text.
+ Any bindings or attempts to set the text property will still
+ work, however.
*/
property alias readOnly: textInput.readOnly
/*!
\qmlproperty string TextField::selectedText
- This read-only property provides the text currently selected in the
- text input.
+ Provides the text currently selected in the text input.
It is equivalent to the following snippet, but is faster and easier
to use.
- \js
+ \code
myTextField.text.toString().substring(myTextField.selectionStart, myTextField.selectionEnd);
- \endjs
+ \endcode
*/
readonly property alias selectedText: textInput.selectedText
@@ -311,8 +337,8 @@ Control {
The cursor position after the last character in the current selection.
- This property is read-only. To change the selection, use select(start,end),
- selectAll(), or selectWord().
+ This property is read-only. To change the selection, use
+ select(start,end), selectAll(), or selectWord().
\sa selectionStart, cursorPosition, selectedText
*/
@@ -333,7 +359,7 @@ Control {
/*!
\qmlproperty string TextField::text
- The text in the TextField.
+ This property contains the text in the TextField.
*/
property alias text: textInput.text
@@ -342,12 +368,13 @@ Control {
Allows you to set a validator on the TextField. When a validator is set
the TextField will only accept input which leaves the text property in
- an or intermediate state. The accepted signal will only be sent
+ an intermediate state. The accepted signal will only be sent
if the text is in an acceptable state when enter is pressed.
- Currently supported validators are IntValidator, DoubleValidator and
- RegExpValidator. An example of using validators is shown below, which allows
- input of integers between 11 and 31 into the text input:
+ Currently supported validators are \l{QtQuick2::IntValidator},
+ \l{QtQuick2::DoubleValidator}, and \l{QtQuick2::RegExpValidator}. An
+ example of using validators is shown below, which allows input of
+ integers between 11 and 31 into the text input:
\code
import QtQuick 2.0
@@ -359,7 +386,7 @@ Control {
}
\endcode
- \sa acceptableInput, inputMask
+ \sa acceptableInput, inputMask, accepted
*/
property alias validator: textInput.validator
@@ -403,7 +430,8 @@ Control {
/*!
\qmlmethod string TextField::getText(int start, int end)
- Removes the section of text that is between the \a start and \a end positions from the TextField.
+ Removes the section of text that is between the \a start and \a end
+ positions from the TextField.
*/
function getText(start, end) {
return textInput.getText(start, end);
@@ -412,7 +440,7 @@ Control {
/*!
\qmlmethod TextField::insert(int position, string text)
- Inserts \a text into the TextField at position.
+ Inserts \a text into the TextField at \a position.
*/
function insert(position, text) {
textInput.insert(position, text);
@@ -421,7 +449,7 @@ Control {
/*!
\qmlmethod bool TextField::isRightToLeft(int start, int end)
- Returns true if the natural reading direction of the editor text
+ Returns \c true if the natural reading direction of the editor text
found between positions \a start and \a end is right to left.
*/
function isRightToLeft(start, end) {
@@ -431,7 +459,8 @@ Control {
/*!
\qmlmethod TextField::paste()
- Replaces the currently selected text by the contents of the system clipboard.
+ Replaces the currently selected text by the contents of the system
+ clipboard.
*/
function paste() {
textInput.paste()
@@ -440,7 +469,7 @@ Control {
/*!
\qmlmethod TextField::redo()
- Redoes the last operation if redo is \l {canRedo}{available}.
+ Performs the last operation if redo is \l {canRedo}{available}.
*/
function redo() {
textInput.redo();
@@ -453,7 +482,7 @@ Control {
If either start or end is out of range, the selection is not changed.
- After calling this, selectionStart will become the lesser
+ After calling select, selectionStart will become the lesser
and selectionEnd will become the greater (regardless of the order passed
to this method).
@@ -484,9 +513,9 @@ Control {
/*!
\qmlmethod TextField::undo()
- Undoes the last operation if undo is \l {canUndo}{available}. Deselects any
- current selection, and updates the selection start to the current cursor
- position.
+ Reverts the last operation if undo is \l {canUndo}{available}. undo()
+ deselects any current selection and updates the selection start to the
+ current cursor position.
*/
function undo() {
textInput.undo();
--
GitLab