Doxygenize TextField
This commit is contained in:
Aurélien Gâteau
parent
eb0644f378
commit
0020ee88bf
@ -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:
|
||||
<code>
|
||||
import QtQuick 1.0
|
||||
TextInput {
|
||||
validator: IntValidator { bottom: 11; top: 31 }
|
||||
focus: true
|
||||
}
|
||||
</code>
|
||||
|
||||
* 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() {
|
||||
|
||||
Loading…
Reference in New Issue
Block a user