From 0020ee88bf3f23c2d6cc8c75caca34afbbf74998 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aur=C3=A9lien=20G=C3=A2teau?= Date: Mon, 17 Dec 2012 23:34:31 +0100 Subject: [PATCH] Doxygenize TextField --- .../plasmacomponents/qml/TextField.qml | 329 ++++++++++-------- 1 file changed, 187 insertions(+), 142 deletions(-) diff --git a/declarativeimports/plasmacomponents/qml/TextField.qml b/declarativeimports/plasmacomponents/qml/TextField.qml index d19e7d886..2f0133f52 100644 --- a/declarativeimports/plasmacomponents/qml/TextField.qml +++ b/declarativeimports/plasmacomponents/qml/TextField.qml @@ -17,207 +17,252 @@ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. */ -/**Documented API -Inherits: - Item - -Imports: - QtQuick 1.1 - -Description: - Creates a simple plasma theme based text field widget. - -Properties: - * font font: - This property holds the font used in the text field. - The default font value is the font from plasma desktop theme. - - * Qt::InputMethodHints inputMethodHints: - This property holds the the currently supported input method hints - for the text field. - The default values is Qt.ImhNone. - - * bool errorHighlight: - This property holds if the text field is highlighted or not - If it is true then the problematic lines will be highlighted. - This feature is defined in the Common API but is unimplemented in plasma components. - - * int cursorPosition: - This property holds the current cursor position. - - * bool readOnly: - This property holds if the text field can be modified by the user interaction. - The default value is false. - - * string selectedText: - This property holds the text selected by the user. - If no text is selected it holds an empty string. - This property is read-only. - - * int selectionEnd: - This property holds the cursor position after the last character in the current selection. - This property is read-only. - - * int selectionStart: - This property holds the cursor position before the first character in the current selection. - This property is read-only. - - * string text: - This property holds the entire text in the text field. - - * string placeholderText: - This property holds the text displayed in when the text is empty. - The default value is empty string, meaning no placeholderText shown. - - * enumeration echoMode: - This property specifies how the text should be displayed in the TextField. - The acceptable values are: - - TextInput.Normal - Displays the text as it is. (Default) - - TextInput.Password - Displays asterixes instead of characters. - - TextInput.NoEcho - Displays nothing. - - TextInput.PasswordEchoOnEdit - Displays all but the current character as asterixes. - The default value is TextInput.Normal - - * string 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 TextInput. - - * Validator validator: - 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 acceptable or 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: - - import QtQuick 1.0 - TextInput { - validator: IntValidator { bottom: 11; top: 31 } - focus: true - } - - - * int maximumLength: - The maximum permitted length of the text in the TextField. - If the text is too long, it is truncated at the limit. - By default, this property contains a value of 32767. - - * bool 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). - This property is always true unless a validator has been set. - If a validator has been set, this property will only be true if the current text is acceptable to the - validator as a final string (not as an intermediate string). - This property is read-only. - - * bool clearButtonShown: - Holds if the button to clear the text from TextField is visible. -Signals: - * accepted(): - This signal is emitted when the text input is accepted. - -Methods: - * void copy(): - Copies the currently selected text to the system clipboard. - - * void cut(): - Moves the currently selected text to the system clipboard. - - * void deselect(): - Removes active text selection. - - * void paste(): - Replaces the currently selected text by the contents of the system clipboard. - - * void select(int start, int end): - Causes the text from start to end to be selected. - If either start or end is out of range, the selection is not changed. - After calling this, selectionStart will become the lesser and selectionEnd will become the greater - (regardless of the order passed to this method). - - * void selectAll(): - Causes all text to be selected. - - * void selectWord(): - Causes the word closest to the current cursor position to be selected. - - * void positionAt(int position): - This function returns the character position at x pixels from the left of the TextField. - Position 0 is before the first character, position 1 is after the first character but before the second, - and so on until position text.length, which is after all characters. - This means that for all x values before the first character this function returns 0, - and for all x values after the last character this function returns text.length. - - * rectangle positionToRectangle(position): - Returns the rectangle at the given position in the text. - The x, y, and height properties correspond to the cursor that would describe that position. -**/ - import QtQuick 1.1 import org.kde.plasma.core 0.1 as PlasmaCore import "private" as Private +/** + * A plasma theme based text field widget. + */ FocusScope { id: textField // Common API + /** + * Whether the text field is highlighted or not + * + * If it is true then the problematic lines will be highlighted. + * + * @warning Not implemented in Plasma components. + */ property bool errorHighlight: false // TODO + + /** + * type:string + * + * The text displayed in when the text is empty. + * + * The default value is an empty string, meaning no placeholderText shown. + */ property string placeholderText + + /** + * type:int + * The currently supported input method hints for the text field. + * + * The default values is Qt.ImhNone. + */ property alias inputMethodHints: textInput.inputMethodHints + + /** + * type:font + * The font used in the text field. + * + * The default font value is the font from plasma desktop theme. + */ property alias font: textInput.font + /** + * type:int + * This property holds the current cursor position. + */ property alias cursorPosition: textInput.cursorPosition + + /** + * type:bool + * This property holds if the text field can be modified by the user interaction. + * + * The default value is false. + */ property alias readOnly: textInput.readOnly - property alias echoMode: textInput.echoMode // Supports TextInput.Normal,TextInput.Password, TextInput.NoEcho, TextInput.PasswordEchoOnEdit + + /** + * type:enum + * + * Specifies how the text should be displayed in the TextField. + * + * The acceptable values are: + * - TextInput.Normal: Displays the text as it is. (Default) + * - TextInput.Password: Displays asterixes instead of characters. + * - TextInput.NoEcho: Displays nothing. + * - TextInput.PasswordEchoOnEdit: Displays all but the current character + * as asterixes. + * + * The default value is TextInput.Normal + */ + property alias echoMode: textInput.echoMode + + property alias passwordCharacter: textInput.passwordCharacter property alias acceptableInput: textInput.acceptableInput // read-only + + /** + * type:string + * + * 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 TextInput. + */ property alias inputMask: textInput.inputMask + + /** + * type:QtObject + * + * 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 acceptable or 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: + * + * @code + * import QtQuick 1.0 + * TextInput { + * validator: IntValidator { bottom: 11; top: 31 } + * focus: true + * } + * @endcode + */ property alias validator: textInput.validator - property alias selectedText: textInput.selectedText // read-only - property alias selectionEnd: textInput.selectionEnd // read-only - property alias selectionStart: textInput.selectionStart // read-only + + /** + * type:string + * The text selected by the user. If no text is selected it holds an empty string. + * + * This property is read-only. + */ + property alias selectedText: textInput.selectedText + + /** + * type:int + * The cursor position after the last character in the current selection. + * + * This property is read-only. + */ + property alias selectionEnd: textInput.selectionEnd + + /** + * type:int + * The cursor position before the first character in the current selection. + * + * This property is read-only. + */ + property alias selectionStart: textInput.selectionStart + + /** + * type:string + * The text in the text field. + */ property alias text: textInput.text + + /** + * type:int + * + * The maximum permitted length of the text in the TextField. If the text + * is too long, it is truncated at the limit. + * + * Default value is 32767. + */ property alias maximumLength: textInput.maximumLength + /** + * Emitted when the text input is accepted. + */ signal accepted() //Plasma api + /** + * Whether the button to clear the text from TextField is visible. + */ property bool clearButtonShown: false + /** + * Copies the currently selected text to the system clipboard. + */ function copy() { textInput.copy(); } + /** + * Replaces the currently selected text by the contents of the system + * clipboard. + */ function paste() { textInput.paste(); } + /** + * Moves the currently selected text to the system clipboard. + */ function cut() { textInput.cut(); } + /** + * Causes the text from start to end to be selected. + * + * If either start or end is out of range, the selection is not changed. + * After calling this, selectionStart will become the lesser and + * selectionEnd will become the greater (regardless of the order passed to + * this method). + * + * @param int start Start of selection + * @param int end End of selection + */ function select(start, end) { textInput.select(start, end); } + /** + * Causes all text to be selected. + */ function selectAll() { textInput.selectAll(); } + /** + * Causes the word closest to the current cursor position to be selected. + */ function selectWord() { textInput.selectWord(); } + /** + * This function returns the character position at x pixels from the left + * of the TextField. + * + * Position 0 is before the first character, position 1 is after the first + * character but before the second, and so on until position text.length, + * which is after all characters. This means that for all x values before + * the first character this function returns 0, and for all x values after + * the last character this function returns text.length. + * + * @param int pos x-coordinate we are interested in. + * @return int the character position + */ function positionAt(pos) { return textInput.positionAt(pos); } + /** + * Returns the rectangle at the given position in the text. + * + * The x, y, and height properties correspond to the cursor that would + * describe that position. + * + * @param int pos the text position + * @param type:rectangle the cursor rectangle + */ function positionToRectangle(pos) { return textInput.positionToRectangle(pos); } - // Set active focus to it's internal textInput. // Overriding QtQuick.Item forceActiveFocus function. function forceActiveFocus() {