基本Widgets(28)：【类】QLineEdit [官翻]

QLineEdit Class

QLineEdit小部件是一个单行文本编辑器。

Header	#include < QLineEdit >
qmake	QT += widgets
Inherits	QWidget
Inherited By

详细说明

行编辑允许用户输入和编辑单行纯文本，其中包含一组有用的编辑功能，包括撤消和重做、剪切和粘贴以及拖放(参见setDragEnabled())。

通过更改行编辑的echoMode()，它还可以用作“write-only”字段，用于密码之类的输入。

文本的长度可以限制为maxLength()。文本可以使用validator()或inputMask()，或两者兼用来任意约束。当在同一行编辑中在验证器和输入掩码之间切换时，最好清除验证器或输入掩码，以防止未定义的行为。

一个相关的类是QTextEdit，它允许多行，富文本编辑。

您可以使用setText()或insert()来更改文本。使用text()检索文本;显示的文本(可能不同，请参阅EchoMode)会被displayText()检索。文本可以通过setSelection()或selectAll()进行选择，选定的文本可以通过cut()、copy()和paste()。文本可以使用setAlignment()进行对齐。

当文本更改时，将发出textChanged信号；当文本更改而不是调用setText时，将发出textEdited信号；当光标移动时，将发出cursorPositionChanged信号；当按下Return或Enter键时，将发出returnPressed信号。

当编辑完成时，因为行编辑丢失了焦点或者回车键被按下，editingFinished()信号被发出。

注意，如果在编辑行上设置了一个验证器，那么只有当验证器返回QValidator::Acceptable时，才会触发returnPressed()/editingFinished()信号。

默认情况下，QLineEdits有一个由平台样式指南指定的框架;你可以通过调用setFrame(false)来关闭它。

下面描述默认的键绑定。行编辑还提供了一个上下文菜单(通常由右击鼠标调用)，该菜单显示了这些编辑选项中的一些。

Keypress	Action
Left Arrow	将光标向左移动一个字符。
Shift+Left Arrow	将文本向左移动并选择一个字符。
Right Arrow	将光标向右移动一个字符。
Shift+Right Arrow	将文本向右移动并选择一个字符。
Home	将光标移到行首。
End	将光标移到行尾。
Backspace	删除光标左侧的字符。
Ctrl+Backspace	删除光标左侧的单词。
Delete	删除光标右侧的字符。
Ctrl+Delete	删除光标右侧的单词。
Ctrl+A	全选。
Ctrl+C	将所选文本复制到剪贴板。
Ctrl+Insert	将所选文本复制到剪贴板。
Ctrl+K	删除到行尾。
Ctrl+V	将剪贴板文本粘贴到行编辑中。
Shift+Insert	将剪贴板文本粘贴到行编辑中。
Ctrl+X	删除所选文本并将其复制到剪贴板。
Shift+Delete	删除所选文本并将其复制到剪贴板。
Ctrl+Z	撤消上一个操作。
Ctrl+Y	重做上次撤消的操作。

表示有效字符的任何其他键序列都会导致将该字符插入到行编辑中。

公共类型

enum ActionPosition

此枚举类型描述行编辑应如何显示要添加的操作小部件。

Constant	Value	Description
QLineEdit::LeadingPosition	0	当使用布局方向Qt::LeftToRight时，小部件分别显示在文本的左侧；当使用Qt::RightToLeft时，小部件分别显示在文本的右侧。
QLineEdit::TrailingPosition	1	使用布局方向Qt::LeftToRight时，小部件分别显示在文本的右侧；使用Qt::RightToLeft时，小部件分别显示在文本的左侧。

enum EchoMode

此枚举类型描述行编辑应如何显示其内容。

Constant	Value	Description
QLineEdit::Normal	0	输入时显示字符。这是默认值。
QLineEdit::NoEcho	1	不要显示任何内容。这可能适用于密码，即使密码的长度也应保密。
QLineEdit::Password	2	显示依赖于平台的密码掩码字符，而不是实际输入的字符。
QLineEdit::PasswordEchoOnEdit	3	编辑时显示输入的字符，然后显示密码字符。

属性

1. acceptableInput: const bool 是否满足inputMask和验证器
   默认情况下，此属性为true。

   Access functions:

   • bool hasAcceptableInput() const

2. alignment: Qt::Alignment 行编辑的对齐方式

   这里允许水平对齐和垂直对齐，Qt::AlignJustify将映射到Qt::AlignLeft。

   默认情况下，该属性包含Qt::AlignLeft和Qt::AlignVCenter的组合。

   Access functions:

   • Qt::Alignment alignment() const
   • void setAlignment(Qt::Alignment flag)

   

3. clearButtonEnabled: bool 行编辑是否在不为空时显示清除按钮
   如果启用，则行编辑在包含某些文本时会显示一个尾部清除按钮，否则行编辑不会显示清除按钮（默认设置）。

   Access functions:

   • bool isClearButtonEnabled() const
   • void setClearButtonEnabled(bool enable)

   

4. cursorMoveStyle: Qt::CursorMoveStyle 行编辑中光标的移动样式
   当此属性设置为Qt::VisualMoveStyle时，线编辑将使用视觉移动样式。无论文字的书写方向如何，按向左箭头键都会使光标向左移动。同样的行为也适用于右箭头键。

   当属性为Qt::LogicalMoveStyle（默认值）时，在LTR文本块中，按左箭头键时增大光标位置，按右箭头键时减小光标位置。如果文本块从右向左，则应用相反的行为。

   Access functions:

   • Qt::CursorMoveStyle cursorMoveStyle() const
   • void setCursorMoveStyle(Qt::CursorMoveStyle style)

   enum Qt::CursorMoveStyle

   此枚举描述文本光标可用的移动样式。选项包括:

   Constant	Value	Description
   Qt::LogicalMoveStyle	0	在从左到右的文本块中，按左箭头键时减小光标位置，按右箭头键时增大光标位置。如果文本块从右向左，则应用相反的行为。
   Qt::VisualMoveStyle	1	无论文字的书写方向如何，按向左箭头键都会始终使光标向左移动。按向右箭头键将始终使光标向右移动。

5. cursorPosition: int 行编辑的当前光标位置
   设置光标位置会在适当时导致重新绘制。
   默认情况下，此属性包含值0。

   Access functions:

   • int cursorPosition() const
   • void setCursorPosition(int)

   

6. displayText: const QString 显示的文本
   如果echoMode为Normal，则返回与text() 相同的值；如果echoMode为Password或PasswordEchoOnEdit，则返回与平台相关的密码掩码字符text() 。length() 的大小，例如“*****”；如果echoMode为NoEcho，则返回空字符串“”。

   默认情况下，此属性包含空字符串。

   Access functions:

   • QString displayText() const

7. dragEnabled: bool 如果用户在某些选定文本上按住并移动鼠标，此属性将保留lineedit是否支持拖动
   默认情况下禁用拖动。

   Access functions:

   • bool dragEnabled() const
   • void setDragEnabled(bool b)

8. echoMode: EchoMode 行编辑的回显模式

   回显模式确定如何向用户显示（或回显）在行编辑中输入的文本。

   最常见的设置是Normal，其中用户输入的文本逐字显示，但QLineEdit还支持允许抑制或隐藏输入的文本的模式:这些模式包括NoEcho、Password和PasswordEchoOnEdit。

   小部件的显示和复制或拖动文本的能力受此设置的影响。

   默认情况下，此属性设置为“Normal”。

   Access functions:

   • QLineEdit::EchoMode echoMode() const
   • void setEchoMode(QLineEdit::EchoMode)

9. frame: bool 行编辑是否使用边框绘制自身

   如果启用（默认设置），线编辑将在框架内绘制自身，否则线编辑将在没有任何框架的情况下绘制自身。

   Access functions:

   • bool hasFrame() const
   • void setFrame(bool)

   

10. hasSelectedText: const bool 是否选择了任何文本。

    如果用户选择了部分或全部文本，则hasSelectedText() 返回true；否则返回false。
    默认情况下，此属性为false。

    Access functions:

    • bool hasSelectedText() const

    

11. inputMask: QString 验证输入掩码
    如果未设置掩码，inputMask() 将返回一个空字符串。

    设置QLineEdit的验证掩码。验证器可以代替掩码使用，也可以与掩码一起使用；请参阅setValidator() 。

    取消设置掩码并通过传递空字符串（“”）返回正常的QLineEdit操作。

    输入掩码是一个输入模板字符串。它可以包含以下元素:

    Mask Characters	定义在此位置被视为有效的输入字符的类别
    Meta Characters	各种特殊元字符
    Separators	所有其他字符都被视为不可变的分隔符

    下表显示了可在输入掩码中使用的掩码和元字符。

    Mask Character	Meaning
    A	所需字母类别的字符，例如A-Z、A-Z。
    a	允许但不要求字母类别的字符。
    N	所需字母或数字类别的字符，例如A-Z、A-Z、0-9。
    n	允许但不要求的字母或数字类别的字符。
    X	需要任何非空白字符。
    x	允许但不是必需的任何非空白字符。
    9	所需数字类别的字符，例如0-9。
    0	允许但不是必需的数字类别的字符。
    D	数字类别的字符，必须大于零，如1-9
    d	允许但不要求大于零的数字类别字符，如1-9。
    #	数字类别的字符，或允许但不要求的加号/减号。
    H	需要十六进制字符。A-F，A-F，0-9。
    h	允许使用十六进制字符，但不是必需的。
    B	需要二进制字符。0-1.
    b	允许使用二进制字符，但不是必需的。

    Meta Character	Meaning
    >	以下所有字母字符都是大写的。
    <	以下所有字母字符均为小写。
    !	关闭案例转换。
    ;c	终止输入掩码并将空白字符设置为C。
    [ ] { }	保留。
    \	使用\对上面列出的特殊字符进行转义，将其用作分隔符。

    当创建或清除时，行编辑将填充一个输入掩码字符串的副本，其中删除了元字符，并且用空白字符（默认情况下，一个空格）替换了掩码字符。

    当设置输入掩码时，text() 方法返回已删除所有空白字符的行编辑内容的修改副本。可以使用 displayText() 读取未修改的内容。

    如果行编辑的当前内容不满足输入掩码的要求，hasAcceptableInput() 方法将返回false。

    示例:

    Mask	Notes
    000.000.000.000;_	IP地址；空格为 _.
    HH:HH:HH:HH:HH:HH;_	MAC地址；空格为 _.
    0000-00-00	ISO日期；空格为空格
    >AAAAA-AAAAA-AAAAA-AAAAA-AAAAA;#	许可证编号；空格为#，所有（字母）字符都转换为大写。

    要获得范围控制（例如IP地址），请使用掩码和验证程序。

    Access functions:

    • QString inputMask() const
    • void setInputMask(const QString &inputMask)

    

12. maxLength: int 文本的最大允许长度
    如果文本太长，将在限制处截断。
    如果发生截断，任何选定的文本都将被取消选中，光标位置设置为0，并显示字符串的第一部分。
    如果行编辑有输入掩码，则掩码定义最大字符串长度。
    默认情况下，此属性包含值32767。

    Access functions:

    • int maxLength() const
    • void setMaxLength(int)

    

13. modified: bool 行编辑的内容是否已被用户修改

    QLineEdit永远不会读取modified标志；它的默认值为false，每当用户更改行编辑的内容时，它都会更改为true。

    这对于需要提供默认值但不知道默认值应该是什么的情况很有用（可能取决于表单上的其他字段）。在没有最佳默认值的情况下开始行编辑，当知道默认值时，如果modified() 返回false（用户没有输入任何文本），则插入默认值。
    调用setText() 将修改的标志重置为false。

    Access functions:

    • bool isModified() const
    • void setModified(bool)

14. placeholderText: QString 行编辑的占位符文本
    设置此属性将使行编辑显示为灰色占位符文本，只要行编辑为空。
    通常，空行编辑会显示占位符文本，即使它有焦点。但是，如果内容水平居中，当行编辑具有焦点时，占位符文本不会显示在光标下。
    默认情况下，此属性包含空字符串。

    Access functions:

    • QString placeholderText() const
    • void setPlaceholderText(const QString &)

    

15. readOnly: bool 行编辑是否为只读
    在只读模式下，用户仍然可以将文本复制到剪贴板，或拖放文本（如果echoMode() 是正常的），但不能对其进行编辑。
    QLineEdit在只读模式下不显示光标。默认情况下，此属性为false。

    Access functions:

    • bool isReadOnly() const
    • void setReadOnly(bool)

16. redoAvailable: const bool 重做是否可用
    一旦用户对行编辑中的文本执行了一个或多个撤消操作，“Redo”即可用。
    默认情况下，此属性为false。

    Access functions:

    • bool isRedoAvailable() const

17. selectedText: const QString 选定的文本
    如果没有选定的文本，则此属性的值为空字符串。
    默认情况下，此属性包含空字符串。

    Access functions:

    • QString selectedText() const

18. text: QString 行编辑的文本
    设置此属性将清除所选内容，清除撤消/重做历史记录，将光标移到行的末尾，并将修改的属性重置为false。使用setText() 插入时，文本不会被验证。
    文本被截断为maxLength() 长度。默认情况下，此属性包含空字符串。

    Access functions:

    • QString text() const
    • void setText(const QString &)

    Notifier signal:

    • void textChanged(const QString &text)

19. undoAvailable: const bool 撤消是否可用
    一旦用户在“行编辑”中修改了文本，“撤消”即可用。
    默认情况下，此属性为false。

    Access functions:

    • bool isUndoAvailable() const

公共函数

构造和析构

1. QLineEdit(const QString &contents, QWidget *parent = nullptr)
2. QLineEdit(QWidget *parent = nullptr)
3. virtual ~QLineEdit()

属性相关

1. bool hasAcceptableInput() const
2. Qt::Alignment alignment() const
3. void setAlignment(Qt::Alignment flag)
4. bool isClearButtonEnabled() const
5. void setClearButtonEnabled(bool enable)
6. Qt::CursorMoveStyle cursorMoveStyle() const
7. void setCursorMoveStyle(Qt::CursorMoveStyle style)
8. int cursorPosition() const
9. void setCursorPosition(int)
10. QString displayText() const
11. bool dragEnabled() const
12. void setDragEnabled(bool b)
13. QLineEdit::EchoMode echoMode() const
14. void setEchoMode(QLineEdit::EchoMode)
15. bool hasFrame() const
16. void setFrame(bool)
17. bool hasSelectedText() const
18. QString inputMask() const
19. void setInputMask(const QString &inputMask)
20. int maxLength() const
21. void setMaxLength(int)
22. bool isModified() const
23. void setModified(bool)
24. QString placeholderText() const
25. void setPlaceholderText(const QString &)
26. bool isReadOnly() const
27. void setReadOnly(bool)
28. bool isRedoAvailable() const
29. QString selectedText() const
30. QString text() const
31. void setText(const QString &)
32. bool isUndoAvailable() const

其他

1. void addAction(QAction *action, QLineEdit::ActionPosition position)
   将操作添加到该位置的操作列表中。

2. QAction * addAction(const QIcon &icon, QLineEdit::ActionPosition position)
   创建一个新动作，该动作在该位置具有给定的图标。

   

3. QMenu * createStandardContextMenu() 上下文菜单
   此函数用于创建标准上下文菜单，当用户用鼠标右键单击“行编辑”时会显示该菜单。它是从默认的contextMenuEvent() 处理程序调用的。弹出菜单的所有权将转移给调用者。

4. QMargins textMargins() const

5. void setTextMargins(int left, int top, int right, int bottom)

6. void setTextMargins(const QMargins &margins)

   QMargins类定义矩形的四个边距。

   

编辑功能

1. void backspace()
2. void del()
3. void deselect()
4. void end(bool mark) 将文本光标移到行尾，除非它已经在行尾
   如果“mark”为真，则文本将朝最后一个位置选择；否则，如果光标移动，则任何选定的文本都将取消选择。
5. void home(bool mark) 将文本光标移到行首，除非它已经在行首
   如果“mark”为true，则朝第一个位置选择文本；否则，如果移动光标，则取消选择任何选定文本。
6. int selectionStart() const
7. int selectionEnd() const
8. int selectionLength() const
9. void setSelection(int start, int length)
10. void insert(const QString &newText)

数据约束

1. QCompleter * completer() const
2. void setCompleter(QCompleter *c)
3. const QValidator * validator() const
4. void setValidator(const QValidator *v)

光标操作

1. void cursorBackward(bool mark, int steps = 1)
2. void cursorForward(bool mark, int steps = 1)
3. int cursorPositionAt(const QPoint &pos)
4. void cursorWordBackward(bool mark)
5. void cursorWordForward(bool mark)

重写的公共函数

1. virtual bool event(QEvent *e) override
2. virtual QVariant inputMethodQuery(Qt::InputMethodQuery property) const override
3. virtual QSize minimumSizeHint() const override
4. virtual QSize sizeHint() const override

公共槽

1. void clear()
2. void copy() const
3. void cut()
4. void paste()
5. void redo()
6. void selectAll()
7. void setText(const QString &)
8. void undo()

信号

1. void cursorPositionChanged(int oldPos, int newPos) 光标位置改变

2. void editingFinished() 编辑结束
   当按下回车键或回车键或行编辑失去焦点时，会发出此信号
   请注意，如果在edit行上设置了validator() 或inputMask() ，并且按下了enter/return，则只有在输入跟随inputMask() 并且validator() 返回QValidator::Acceptable时，才会发出editingFinished() 信号。

3. void inputRejected() 输入被拒

   当用户按下一个不被认为是可接受输入的键时，就会发出这个信号。例如，如果按键导致验证器的validate() 调用返回Invalid。另一种情况是试图输入超过行编辑最大长度的字符。
   注意:在部分文本被接受但并非全部文本被接受的情况下，仍会发出此信号。例如，如果设置了最大长度，并且粘贴时剪贴板文本长于最大长度。

4. void returnPressed() 按下回车键或回车键时发出此信号

   请注意，如果在编辑行上设置了validator() 或inputMask() ，则仅当输入跟随inputMask() 并且validator() 返回QValidator::Acceptable时，才会发出returnPressed() 信号。

5. void selectionChanged() 每当选择改变时，就会发出此信号

6. void textChanged(const QString &text) 每当文本改变时，就会发出这个信号

   text参数是新文本。
   与textEdited() 不同，当以编程方式更改文本时，也会发出此信号，例如，通过调用setText() 。

7. void textEdited(const QString &text) 每当编辑文本时，就会发出此信号

   text参数是新文本。
   与textChanged() 不同，以编程方式更改文本时（例如，通过调用setText() ）不会发出此信号。

受保护的函数

1. QRect cursorRect() const
2. void initStyleOption(QStyleOptionFrame *option) const

重写的受保护的函数

1. virtual void changeEvent(QEvent *ev) override
2. virtual void contextMenuEvent(QContextMenuEvent *event) override
3. virtual void dragEnterEvent(QDragEnterEvent *e) override
4. virtual void dragLeaveEvent(QDragLeaveEvent *e) override
5. virtual void dragMoveEvent(QDragMoveEvent *e) override
6. virtual void dropEvent(QDropEvent *e) override
7. virtual void focusInEvent(QFocusEvent *e) override
8. virtual void focusOutEvent(QFocusEvent *e) override
9. virtual void inputMethodEvent(QInputMethodEvent *e) override
10. virtual void keyPressEvent(QKeyEvent *event) override
11. virtual void mouseDoubleClickEvent(QMouseEvent *e) override
12. virtual void mouseMoveEvent(QMouseEvent *e) override
13. virtual void mousePressEvent(QMouseEvent *e) override
14. virtual void mouseReleaseEvent(QMouseEvent *e) override
15. virtual void paintEvent(QPaintEvent *) override

相关代码

#include <QtWidgets>
#define WidgetType QLineEdit
int i=0,j=0;
QList<WidgetType *> widgetList;
QList<QLabel *> labelList;

void addFrame(QGridLayout *mainLayout,QWidget *parent){
    QLineEdit *widget = new QLineEdit(parent);
    widgetList.append (widget);
    QLabel *label = new QLabel(parent);
    labelList.append (label);
    QFrame *frame = new QFrame(parent);
    frame->setFrameStyle (QFrame::Panel | QFrame::Plain);

//    label->setAlignment (Qt::AlignCenter);

    auto *vBox = new QVBoxLayout(frame);
    vBox->addWidget (label);
    vBox->addWidget (widget);
    mainLayout->addWidget (frame,i,j);
    j++;
}

void setLabelText(int i,QString text){
    if(i >= labelList.count ()){
        return;
    }
    QLabel *label = labelList.at (i);
    label->setText (text);
}

WidgetType* getWidget(int i){
    if(i >= widgetList.count ()){
        qDebug() <<   __LINE__ <<"行 getWidget(int i) 函数 变量"<<    i  << "超出范围";
        i = 0;          // 超出范围默认使用 0
    }
    return  widgetList.at (i);
}

int main(int argc, char *argv[])
{
    QApplication::setStyle (QStyleFactory::create ("fusion")); //windowsvista fusion

    QApplication app(argc,argv);
    app.setApplicationName ("QLineEdit");

    QDialog w;
    w.setWindowFlag (Qt::WindowContextHelpButtonHint,false);

    auto mainLayout = new QGridLayout(&w);
    i = j = 0;
    addFrame (mainLayout,&w);

//    getWidget (0)->setClearButtonEnabled (true);
    getWidget (0)->setText ("设置小部件的文本边距");
    getWidget (0)->setTextMargins (20,10,20,10);

    setLabelText (0,"setTextMargins (20,10,20,10)");

    w.show ();
    app.exec();
    return 0;
}

参考

• Line Edits Example