/****************************************************************************
**
** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the Qt Components project.
**
** $QT_BEGIN_LICENSE:BSD$
** You may use this file under the terms of the BSD license as follows:
**
** "Redistribution and use in source and binary forms, with or without
** modification, are permitted provided that the following conditions are
** met:
**   * Redistributions of source code must retain the above copyright
**     notice, this list of conditions and the following disclaimer.
**   * Redistributions in binary form must reproduce the above copyright
**     notice, this list of conditions and the following disclaimer in
**     the documentation and/or other materials provided with the
**     distribution.
**   * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
**     the names of its contributors may be used to endorse or promote
**     products derived from this software without specific prior written
**     permission.
**
** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
    \qmlclass TextField
    \inherits Item
    \ingroup qt-components
    \since 4.7
    \brief The TextField element 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 validator or inputMask), 
    and setting echoMode to an appropriate value enables TextInput to be used for a 
    password input field.
    
    \code
    TextField {
        placeholderText: "Default text"
        maximumLength: 80
    }    
    
    TextField {
        text: "read only text field"
        readOnly:  true
    }    
    \endcode
*/

/*!
    \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).
*/

/*!
    \qmlproperty int TextField::cursorPosition

    The position of the cursor in the TextField.
*/

/*!
    \qmlproperty enumeration TextField::echoMode

    Specifies how the text should be displayed in the TextField.
    \list
    \o \c TextInput.Normal - displays the text as it is (default).
    \o \c TextInput.Password - displays asterisks instead of characters.
    \o \c TextInput.NoEcho - displays nothing.
    \o \c TextInput.PasswordEchoOnEdit - displays all but the current character as asterisks.
    \endlist
*/

/*!
    \qmlproperty Font TextField::font

    Font properties for the text.
*/

/*!
    \qmlproperty string TextField::inputMask

    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.
*/

/*!
    By default all attributes are disabled.
    \qmlproperty Item TextField::platformSipAttributes

    Sets the software input panel attributes.

    This property should be set to an instance of SipAttributes, which can be used to e.g. highlight or disable the action key.
*/

/*!
    \qmlproperty Qt::InputMethodHints TextField::inputMethodHints

    Sets the current input method hints.
*/

/*!
    \qmlproperty string TextField::placeholderText

    Text that appear if there is no focus and no content on the component.
*/

/*!
    \qmlproperty bool TextField::readOnly

    Property default is false.
    
    Whether the user can interact with the TextField item. If this property is set to true the user cannot edit the text.
*/

/*!
    \qmlproperty string TextField::selectedText

    This read-only property provides the text currently selected in the text edit.
*/

/*!
    \qmlproperty int TextField::selectionEnd

    The cursor position after the last character in the current selection.
*/

/*!
    \qmlproperty int TextField::selectionStart

    The cursor position before the first character in the current selection.
*/

/*!
    \qmlproperty string TextField::text

    The text to display. Does not contain the pre-edit text.
*/

/*!
    \qmlproperty QValidator TextField::validator

    Sets a validator on the TextField. When a validator is set the TextField only accepts input which leaves the text property in an acceptable or intermediate state. The accepted signal is only sent if the text is in an acceptable state when enter is pressed.
    Currently supported validators are IntValidator, DoubleValidator and RegExpValidator.
*/

/*!
    \qmlproperty bool TextField::errorHighlight

    Allows you to show error highlight for the TextField.

    Usage for mandatory field:
    \qml
    TextField {
        //...
        errorHighlight: !acceptableInput
        validator: IntValidator{bottom: 1000; top: 2000;}
    }
    \endqml

    Usage for optional field:
    \qml
    TextField {
        errorHighlight: text ? !acceptableInput : false
        //...
    }
    \endqml
*/

/*!
    \qmlproperty bool TextField::enableSoftwareInputPanel

    Disables the default software input panel. Enabled by default.
*/

/*!
    \qmlproperty Item TextField::platformStyle

    Element holding the platform specific styling.
*/

/*!
    \qmlproperty bool TextField::platformWesternNumericInputEnforced

    In some rare cases it is required  to have a western numeric input panel even
    when the default input method is set to a language that uses non-western digits
    (like arabic). This may be the case when the input field expects, for example,
    credit card numbers.
    
    The default is false.
*/

/*!
    \qmlproperty Component TextField::customSoftwareInputPanel

    Replaces the default software input panel with your own.
*/

/*!
    \qmlmethod TextField::copy()
    
    Copies the selected text into the clipboard.
*/

/*!    
    \qmlmethod TextField::paste()
       
    Pastes the text from the clipboard in the current cursor position.
*/

/*!    
    \qmlmethod TextField::cut()
        
    Cuts the selected text and copies it on the clipboard.    
*/

/*!
    \qmlmethod TextField::forceActiveFocus()
    
    Forces active focus on the item. This method sets the focus on the item and makes sure that all the focus scopes higher in the object hierarchy are also given focus.
*/

/*!    
    \qmlmethod TextField::select(start, end)
    
    Selects the text between position \a start and \a end.
*/

/*!    
    \qmlmethod TextField::selectAll()
    
    Selects all the text.
*/

/*!    
    \qmlmethod TextField::selectWord()
    
    Selects the word nearest to the cursor position
*/

/*!    
    \qmlmethod TextField::positionAt(x, y)
    
    Returns the text position closest to pixel position (\a x, \a y).
    
    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.
*/

/*!    
    \qmlmethod TextField::positionToRectangle(pos)
    
    Returns the rectangle at the given position \a pos in the text. The x, y, and height properties correspond to the cursor that would describe that position.
*/

/*!
    \qmlmethod TextField::openSoftwareInputPanel()

    Opens software input panels like virtual keyboards for typing, useful for customizing when you want the input keyboard to be shown and hidden in your application.
*/

/*!
    \qmlmethod TextField::closeSoftwareInputPanel()

    Closes a software input panel like a virtual keyboard shown on the screen, useful for customizing when you want the input keyboard to be shown and hidden in your application.
*/
