/****************************************************************************
**
** 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 TextArea
    \inherits Item
    \ingroup qt-components
    \since 4.7
    \brief The TextArea item displays multiple lines of editable formatted text

    The TextArea item displays multiple lines of editable formatted text.
    
    \code
    TextArea {
        anchors {left: parent.left; right: parent.right;}
        text: "This is a\nmultiline\ntext area"
        height: Math.max (200, implicitHeight)
    }    
    \endcode
*/

/*!
    \qmlproperty int TextArea::cursorPosition

    The position of the cursor in the TextArea.
*/

/*!
    \qmlproperty Font TextArea::font

    Font properties for the text.
*/

/*!
    \qmlproperty enumeration TextArea::horizontalAlignment
    \qmlproperty enumeration TextArea::verticalAlignment
    
    Sets the horizontal and vertical alignment of the text within the width and height of the TextEdit item. By default, the text is top-left aligned.
    Valid values for horizontalAlignment are:
    \list
        \o \c TextEdit.AlignLeft (default)
        \o \c TextEdit.AlignRight
        \o \c TextEdit.AlignHCenter
    \endlist
    Valid values for verticalAlignment are:
    \list
        \o \c TextEdit.AlignTop (default)
        \o \c TextEdit.AlignBottom TextEdit.AlignVCenter
    \endlist
*/

/*!
    \qmlproperty string TextArea::placeholderText

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

/*!
    \qmlproperty bool TextArea::readOnly
    
    Property default is \c false.
    
    Sets whether the user can interact with the TextEdit item. If this property is set to true the user cannot edit the text.

*/

/*!
    \qmlproperty string TextArea::selectedText

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

/*!
    \qmlproperty int TextArea::selectionEnd

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

/*!
    \qmlproperty int TextArea::selectionStart

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

/*!
    \qmlproperty Item TextArea::platformStyle

    Element holding the platform specific styling.
*/

/*!
    \qmlproperty bool TextArea::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 area expects, for example,
    credit card numbers.
    
    The default is false.
*/

/*!
    \qmlproperty string TextArea::text

    The text to display. If the text format is AutoText the text edit will automatically determine whether the text should be treated as rich text.
*/

/*!
    \qmlproperty enumeration TextArea::textFormat

    The way the text property are displayed.
    \c TextEdit.AutoText
    \c TextEdit.PlainText
    \c TextEdit.RichText
    \c TextEdit.StyledText
*/

/*!
    The default is TextEdit.NoWrap. If you set a width, consider using TextEdit.Wrap.
    \qmlproperty enumeration TextArea::wrapMode

    Set this property to wrap the text to the width of the TextArea item. The text wraps only if an explicit width has been set.
    \list
    \o \c TextEdit.NoWrap - no wrapping is performed. If the text contains insufficient newlines, then implicitWidth exceeds a set width.
    \o \c TextEdit.WordWrap - wrapping is done on word boundaries only. If a word is too long, implicitWidth exceeds a set width.
    \o \c TextEdit.WrapAnywhere - wrapping is done at any point on a line, even if it occurs in the middle of a word.
    \o \c TextEdit.Wrap - if possible, wrapping occurs at a word boundary; otherwise it occurs at the appropriate point on the line, even in the middle of a word.
    \endlist
*/

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

    Use this property to set software input panel attributes. 

    This property should be set to an instance of SipAttributes, which are be used for example to highlight or disable the action key. 
*/

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

    Sets the current input method hints.
*/

/*!
    \qmlproperty bool TextArea::enableSoftwareInputPanel

    Allows you to disable the default software input panel. Enabled by default.
*/

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

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

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

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

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

/*!    
    \qmlmethod TextArea::selectAll()
    
    Selecta all the text.
*/

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

/*!    
    \qmlmethod TextArea::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 TextArea::positionToRectangle(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.
*/

/*!
    \qmlmethod TextArea::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 TextArea::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.
*/

/*!
    Note that if a TextArea is inside a Flickable item then Flickable's pressDelay property should be set (e.g. to 100)to avoid undesirable effects. Otherwise panning a focused TextArea that has lots of text will be difficult.
*/
