q3textedit.cpp

奇趣公司比较新的qt/emd版本

    You can scroll to an anchor in the text, e.g.
    \c{<a name="anchor">} with scrollToAnchor(). The find() function
    can be used to find and select a given string within the text.

    A read-only Q3TextEdit provides the same functionality as the
    (obsolete) QTextView. (QTextView is still supplied for
    compatibility with old code.)

    \section2 Read-only key bindings

    When Q3TextEdit is used read-only the key-bindings are limited to
    navigation, and text may only be selected with the mouse:
    \table
    \header \i Keypresses \i Action
    \row \i Qt::UpArrow        \i Move one line up
    \row \i Qt::DownArrow        \i Move one line down
    \row \i Qt::LeftArrow        \i Move one character left
    \row \i Qt::RightArrow        \i Move one character right
    \row \i PageUp        \i Move one (viewport) page up
    \row \i PageDown        \i Move one (viewport) page down
    \row \i Home        \i Move to the beginning of the text
    \row \i End                \i Move to the end of the text
    \row \i Shift+Wheel
         \i Scroll the page horizontally (the Wheel is the mouse wheel)
    \row \i Ctrl+Wheel        \i Zoom the text
    \endtable

    The text edit may be able to provide some meta-information. For
    example, the documentTitle() function will return the text from
    within HTML \c{<title>} tags.

    The text displayed in a text edit has a \e context. The context is
    a path which the text edit's Q3MimeSourceFactory uses to resolve
    the locations of files and images. It is passed to the
    mimeSourceFactory() when quering data. (See Q3TextEdit() and
    \l{context()}.)

    \target logtextmode
    \section2 Using Q3TextEdit in Qt::LogText Mode

    Setting the text format to Qt::LogText puts the widget in a special
    mode which is optimized for very large texts. In this mode editing
    and rich text support are disabled (the widget is explicitly set
    to read-only mode). This allows the text to be stored in a
    different, more memory efficient manner. However, a certain degree
    of text formatting is supported through the use of formatting
    tags. A tag is delimited by \c < and \c {>}. The characters \c
    {<}, \c > and \c & are escaped by using \c {&lt;}, \c {&gt;} and
    \c {&amp;}. A tag pair consists of a left and a right tag (or
    open/close tags). Left-tags mark the starting point for
    formatting, while right-tags mark the ending point. A right-tag
    always start with a \c / before the tag keyword. For example \c
    <b> and \c </b> are a tag pair. Tags can be nested, but they
    have to be closed in the same order as they are opened. For
    example, \c <b><u></u></b> is valid, while \c
    <b><u></b></u> will output an error message.

    By using tags it is possible to change the color, bold, italic and
    underline settings for a piece of text. A color can be specified
    by using the HTML font tag \c {<font color=colorname>}. The color
    name can be one of the color names from the X11 color database, or
    a RGB hex value (e.g \c {#00ff00}). Example of valid color tags:
    \c {<font color=red>}, \c{<font color="light blue">},\c {<font
    color="#223344">}. Bold, italic and underline settings can be
    specified by the tags \c {<b>}, \c <i> and \c {<u>}. Note that a
    tag does not necessarily have to be closed. A valid example:
    \code
    This is <font color=red>red</font> while <b>this</b> is <font color=blue>blue</font>.
    <font color=green><font color=yellow>Yellow,</font> and <u>green</u>.
    \endcode

    Stylesheets can also be used in Qt::LogText mode. To create and use a
    custom tag, you could do the following:
    \code
    Q3TextEdit * log = new Q3TextEdit(this);
    log->setTextFormat(Qt::LogText);
    Q3StyleSheetItem * item = new Q3StyleSheetItem(log->styleSheet(), "mytag");
    item->setColor("red");
    item->setFontWeight(QFont::Bold);
    item->setFontUnderline(true);
    log->append("This is a <mytag>custom tag</mytag>!");
    \endcode
    Note that only the color, bold, underline and italic attributes of
    a Q3StyleSheetItem is used in Qt::LogText mode.

    Note that you can use setMaxLogLines() to limit the number of
    lines the widget can hold in Qt::LogText mode.

    There are a few things that you need to be aware of when the
    widget is in this mode:
    \list
    \i Functions that deal with rich text formatting and cursor
    movement will not work or return anything valid.
    \i Lines are equivalent to paragraphs.
    \endlist

    \section1 Using Q3TextEdit as an Editor

    All the information about using Q3TextEdit as a display widget also
    applies here.

    The current format's attributes are set with setItalic(),
    setBold(), setUnderline(), setFamily() (font family),
    setPointSize(), setColor() and setCurrentFont(). The current
    paragraph's alignment is set with setAlignment().

    Use setSelection() to select text. The setSelectionAttributes()
    function is used to indicate how selected text should be
    displayed. Use hasSelectedText() to find out if any text is
    selected. The currently selected text's position is available
    using getSelection() and the selected text itself is returned by
    selectedText(). The selection can be copied to the clipboard with
    copy(), or cut to the clipboard with cut(). It can be deleted with
    removeSelectedText(). The entire text can be selected (or
    unselected) using selectAll(). Q3TextEdit supports multiple
    selections. Most of the selection functions operate on the default
    selection, selection 0. If the user presses a non-selecting key,
    e.g. a cursor key without also holding down Shift, all selections
    are cleared.

    Set and get the position of the cursor with setCursorPosition()
    and getCursorPosition() respectively. When the cursor is moved,
    the signals currentFontChanged(), currentColorChanged() and
    currentAlignmentChanged() are emitted to reflect the font, color
    and alignment at the new cursor position.

    If the text changes, the textChanged() signal is emitted, and if
    the user inserts a new line by pressing Return or Enter,
    returnPressed() is emitted. The isModified() function will return
    true if the text has been modified.

    Q3TextEdit provides command-based undo and redo. To set the depth
    of the command history use setUndoDepth() which defaults to 100
    steps. To undo or redo the last operation call undo() or redo().
    The signals undoAvailable() and redoAvailable() indicate whether
    the undo and redo operations can be executed.

    \section2 Editing key bindings

    The list of key-bindings which are implemented for editing:
    \table
    \header \i Keypresses \i Action
    \row \i Backspace \i Delete the character to the left of the cursor
    \row \i Delete \i Delete the character to the right of the cursor
    \row \i Ctrl+A \i Move the cursor to the beginning of the line
    \row \i Ctrl+B \i Move the cursor one character left
    \row \i Ctrl+C \i Copy the marked text to the clipboard (also
                      Ctrl+Insert under Windows)
    \row \i Ctrl+D \i Delete the character to the right of the cursor
    \row \i Ctrl+E \i Move the cursor to the end of the line
    \row \i Ctrl+F \i Move the cursor one character right
    \row \i Ctrl+H \i Delete the character to the left of the cursor
    \row \i Ctrl+K \i Delete to end of line
    \row \i Ctrl+N \i Move the cursor one line down
    \row \i Ctrl+P \i Move the cursor one line up
    \row \i Ctrl+V \i Paste the clipboard text into line edit
                      (also Shift+Insert under Windows)
    \row \i Ctrl+X \i Cut the marked text, copy to clipboard
                      (also Shift+Delete under Windows)
    \row \i Ctrl+Z \i Undo the last operation
    \row \i Ctrl+Y \i Redo the last operation
    \row \i Qt::LeftArrow            \i Move the cursor one character left
    \row \i Ctrl+Qt::LeftArrow  \i Move the cursor one word left
    \row \i Qt::RightArrow            \i Move the cursor one character right
    \row \i Ctrl+Qt::RightArrow \i Move the cursor one word right
    \row \i Qt::UpArrow            \i Move the cursor one line up
    \row \i Ctrl+Qt::UpArrow    \i Move the cursor one word up
    \row \i Qt::DownArrow            \i Move the cursor one line down
    \row \i Ctrl+Down Arrow \i Move the cursor one word down
    \row \i PageUp            \i Move the cursor one page up
    \row \i PageDown            \i Move the cursor one page down
    \row \i Home            \i Move the cursor to the beginning of the line
    \row \i Ctrl+Home            \i Move the cursor to the beginning of the text
    \row \i End                    \i Move the cursor to the end of the line
    \row \i Ctrl+End            \i Move the cursor to the end of the text
    \row \i Shift+Wheel            \i Scroll the page horizontally
                            (the Wheel is the mouse wheel)
    \row \i Ctrl+Wheel            \i Zoom the text
    \endtable

    To select (mark) text hold down the Shift key whilst pressing one
    of the movement keystrokes, for example, \e{Shift+Right Arrow}
    will select the character to the right, and \e{Shift+Ctrl+Right
    Arrow} will select the word to the right, etc.

    By default the text edit widget operates in insert mode so all
    text that the user enters is inserted into the text edit and any
    text to the right of the cursor is moved out of the way. The mode
    can be changed to overwrite, where new text overwrites any text to
    the right of the cursor, using setOverwriteMode().
*/

/*!
    \enum Q3TextEdit::AutoFormattingFlag

    \value AutoNone Do not perform any automatic formatting
    \value AutoBulletList Only automatically format bulletted lists
    \value AutoAll Apply all available autoformatting
*/


/*!
    \enum Q3TextEdit::KeyboardAction

    This enum is used by doKeyboardAction() to specify which action
    should be executed:

    \value ActionBackspace  Delete the character to the left of the
    cursor.

    \value ActionDelete  Delete the character to the right of the
    cursor.

    \value ActionReturn  Split the paragraph at the cursor position.

    \value ActionKill If the cursor is not at the end of the
    paragraph, delete the text from the cursor position until the end
    of the paragraph. If the cursor is at the end of the paragraph,
    delete the hard line break at the end of the paragraph: this will
    cause this paragraph to be joined with the following paragraph.

    \value ActionWordBackspace Delete the word to the left of the
    cursor position.

    \value ActionWordDelete Delete the word to the right of the
    cursor position

*/

/*!
    \enum Q3TextEdit::VerticalAlignment

    This enum is used to set the vertical alignment of the text.

    \value AlignNormal Normal alignment
    \value AlignSuperScript Superscript
    \value AlignSubScript Subscript
*/

/*!
    \enum Q3TextEdit::TextInsertionFlags

    \internal

    \value RedoIndentation
    \value CheckNewLines
    \value RemoveSelected
*/


/*!
    \fn void Q3TextEdit::copyAvailable(bool yes)

    This signal is emitted when text is selected or de-selected in the
    text edit.

    When text is selected this signal will be emitted with \a yes set
    to true. If no text has been selected or if the selected text is
    de-selected this signal is emitted with \a yes set to false.

    If \a yes is true then copy() can be used to copy the selection to
    the clipboard. If \a yes is false then copy() does nothing.

    \sa selectionChanged()
*/


/*!
    \fn void Q3TextEdit::textChanged()

    This signal is emitted whenever the text in the text edit changes.

    \sa setText() append()
*/

/*!
    \fn void Q3TextEdit::selectionChanged()

    This signal is emitted whenever the selection changes.

    \sa setSelection() copyAvailable()
*/

/*!  \fn Q3TextDocument *Q3TextEdit::document() const

    \internal

  This function returns the Q3TextDocument which is used by the text
  edit.
*/

/*!  \fn void Q3TextEdit::setDocument(Q3TextDocument *doc)

    \internal

  This function sets the Q3TextDocument which should be used by the text
  edit to \a doc. This can be used, for example, if you want to
  display a document using multiple views. You would create a
  Q3TextDocument and set it to the text edits which should display it.
  You would need to connect to the textChanged() and
  selectionChanged() signals of all the text edits and update them all
  accordingly (preferably with a slight delay for efficiency reasons).
*/

/*!
    \enum Q3TextEdit::CursorAction

    This enum is used by moveCursor() to specify in which direction
    the cursor should be moved:

    \value MoveBackward  Moves the cursor one character backward

    \value MoveWordBackward Moves the cursor one word backward

    \value MoveForward  Moves the cursor one character forward

    \value MoveWordForward Moves the cursor one word forward

    \value MoveUp  Moves the cursor up one line

    \value MoveDown  Moves the cursor down one line

    \value MoveLineStart  Moves the cursor to the beginning of the line

    \value MoveLineEnd Moves the cursor to the end of the line

    \value MoveHome  Moves the cursor to the beginning of the document

    \value MoveEnd Moves the cursor to the end of the document

    \value MovePgUp  Moves the cursor one viewport page up

    \value MovePgDown  Moves the cursor one viewport page down
*/

/*!
    \property Q3TextEdit::overwriteMode
    \brief the text edit's overwrite mode

    If false (the default) characters entered by the user are inserted
    with any characters to the right being moved out of the way. If
    true, the editor is in overwrite mode, i.e. characters entered by
    the user overwrite any characters to the right of the cursor
    position.
*/

/*!
    \fn void Q3TextEdit::setCurrentFont(const QFont &f)

    Sets the font of the current format to \a f.

    If the widget is in Qt::LogText mode this function will do
    nothing. Use setFont() instead.

    \sa currentFont() setPointSize() setFamily()
*/

/*!
    \property Q3TextEdit::undoDepth
    \brief the depth of the undo history

    The maximum number of steps in the undo/redo history. The default
    is 100.

    \sa undo() redo()
*/

/*!
    \fn void Q3TextEdit::undoAvailable(bool yes)

    This signal is emitted when the availability of undo changes. If
    \a yes is true, then undo() will work until undoAvailable(false)