基本Widgets(25)：【类】QLabel [官翻]

QLabel Class

QLabel小部件提供文本或图像显示。

Header	#include < QLabel >
qmake	QT += widgets
Inherits	QFrame
Inherited By

详细说明

QLabel用于显示文本或图像。不提供用户交互功能。标签的视觉外观可以以各种方式配置，并且可以用于为另一个小部件指定焦点助记键。

QLabel可以包含以下任何内容类型:

Content	Setting
Plain text	将QString传递给setText() 。
Rich text	将包含富文本的QString传递给setText() 。
A pixmap	将QPixmap传递给setPixmap() 。
A movie	将QMovie传递给setMovie() 。
A number	将int或double传递给setNum() ，后者将数字转换为纯文本。
Nothing	与空纯文本相同。这是默认值。由clear() 设置。

警告:当将QString传递给构造函数或调用setText() 时，请确保清理您的输入，因为QLabel试图猜测它是将文本显示为纯文本还是富文本（html4标记的子集）。您可能希望显式调用setTextFormat() ，例如，如果希望文本为纯格式，但无法控制文本源（例如，在显示从Web加载的数据时）。

使用这些函数中的任何一个更改内容时，将清除以前的任何内容。

默认情况下，标签显示左对齐、垂直居中的文本和图像，其中要显示的文本中的任何选项卡都将自动展开。但是，QLabel的外观可以通过几种方式进行调整和微调。

可以使用setAlignment() 和setIndent() 调整QLabel小部件区域中内容的位置。文本内容还可以使用setWordWrap() 沿单词边界换行。例如，此代码设置了一个凹陷面板，其右下角有两行文本（两行都与标签的右侧齐平）:

#include <QtWidgets>
int main(int argc, char *argv[])
{
    QApplication app(argc,argv);
    app.setApplicationName ("QLabel");

    QWidget w;

    QLabel *label = new QLabel();
    label->setFrameStyle(QFrame::Panel | QFrame::Sunken);
    label->setText("first line\nsecond line");
    label->setAlignment(Qt::AlignBottom | Qt::AlignRight);

    QHBoxLayout *mainLayout = new QHBoxLayout(&w);
    mainLayout->addWidget (label);

    w.resize (280,100);
    w.show ();
    app.exec();
    return 0;
}

QLabel从QFrame继承的属性和函数也可用于指定要用于任何给定标签的小部件框架。

QLabel通常用作交互式小部件的标签。为此，QLabel提供了一种有用的机制，用于添加助记符（参见QKeySequence），该助记符将键盘焦点设置到另一个小部件（称为QLabel的“buddy”）。例如:

 QLineEdit *phoneEdit = new QLineEdit(this);
 QLabel *phoneLabel = new QLabel("&Phone:", this);
 phoneLabel->setBuddy(phoneEdit);

在本例中，当用户按Alt+P时，键盘焦点转移到标签的好友（QLineEdit）。如果好友是按钮（继承自QAbstractButton），则触发助记符将模拟按钮单击。

属性

1. alignment: Qt::Alignment 标签内容的对齐方式

   默认情况下，标签的内容是左对齐和垂直居中的。

   Access functions:

   • Qt::Alignment alignment() const

   • void setAlignment(Qt::Alignment)

     

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

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

   注意:标签上设置的textInteractionFlags需要包括TextSelectableByMouse或TextSelectableByKeyboard。
   Qt4.7中引入了这个属性。

   Access functions:

   • bool hasSelectedText() const

   

3. indent: int 以像素为单位保存标签的文本缩进

   如果标签显示文本，如果alignment() 为Qt::AlignLeft，缩进将应用于左边缘；如果alignment() 为Qt::AlignRight，缩进将应用于右边缘；如果alignment() 为Qt::AlignTop，缩进将应用于上边缘；如果alignment() 为Qt::AlignBottom，缩进将应用于下边缘。

   如果缩进为负，或者未设置缩进，则标签将按如下方式计算有效缩进:如果frameWidth() 为0，则有效缩进为0。如果frameWidth() 大于0，则有效缩进将变为小部件当前字体() 的“x”字符宽度的一半。

   默认情况下，缩进是-1，这意味着有效缩进是以上述方式计算的。

   Access functions:

   • int indent() const
   • void setIndent(int)

   

4. margin: int 边距的宽度

   边距是框架的最里面像素和内容的最外像素之间的距离。

   默认边距为0。

   Access functions:

   • int margin() const
   • void setMargin(int)

   

5. openExternalLinks: bool 是否使用QDesktopServices::openUrl()自动打开链接,而不是发出linkActivated() 信号

   注意:标签上设置的textInteractionFlags需要包括LinksAccessibleByMouse或LinksAccessibleByKeyboard。
   默认值为false。

   Access functions:

   • bool openExternalLinks() const
   1. void setOpenExternalLinks(bool open)

   

6. pixmap: QPixmap 标签的pixmap

   以前，Qt提供了pixmap() 的一个版本，它通过指针返回pixmap。该版本现在已被弃用。要保持与旧代码的兼容性，可以显式区分by pointer函数和by value函数:

    const QPixmap *pixmapPtr = label->pixmap();
    QPixmap pixmapVal = label->pixmap(Qt::ReturnByValue);
   

   如果使用 QT_DISABLE_DEPRECATED_BEFORE 宏禁用了不推荐使用的版本，则可以省略QT::ReturnByValue，如下所示:

   QPixmap pixmapVal = label->pixmap();
   

   如果没有设置pixmap，则不推荐使用的getter函数将返回nullptr。
   设置pixmap将清除以前的任何内容。好友的快捷方式（如果有）会被禁用。

   Access functions:

   • QPixmap pixmap(Qt::ReturnByValueConstant) const
   1. void setPixmap(const QPixmap &)

   

7. scaledContents: bool 是否缩放其内容以填充所有可用空间
   当启用并且标签显示一个pixmap时，它将缩放pixmap以填充可用空间。
   此属性的默认值为false。

   Access functions:

   • bool hasScaledContents() const
   1. void setScaledContents(bool)
   

8. selectedText: const QString 选定的文本
   如果没有选定的文本，则此属性的值为空字符串。默认情况下，此属性包含空字符串。
   注意:标签上设置的textInteractionFlags需要包括TextSelectableByMouse或TextSelectableByKeyboard。

   Access functions:

   • QString selectedText() const

9. text: QString 标签的文本

   如果未设置文本，则返回空字符串。设置文本将清除以前的任何内容。

   根据文本格式设置，文本将被解释为纯文本或富文本；请参阅setTextFormat() 。默认设置为Qt::AutoText；即QLabel将尝试自动检测文本集的格式。有关富文本的定义，请参见支持的HTML子集。

   如果已设置好友，则会根据新文本更新好友助记键。

   请注意，QLabel非常适合显示小型富文本文档，例如从标签的调色板和字体属性获取文档特定设置（字体、文本颜色、链接颜色）的小型文档。对于大型文档，请改用只读模式下的QTextEdit。QTextEdit还可以在必要时提供滚动条。

   注意:如果文本包含富文本，此函数将启用鼠标跟踪。

   Access functions:

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

   

       QString str  = "<h1>Hello</h1> <i>Qt!</i>"
                      "<hr ><br>"
                      "<img src = 'file:///E:/Users/Desktop/qt5_particles.jpg'/>";
       label0->setText( str);
       // 可惜不能支持http协议，只有本地文件传输
   

10. textFormat: Qt::TextFormat 标签的文本格式
    有关可能选项的说明，请参见Qt::TextFormat枚举。
    默认格式是Qt::AutoText。

    Access functions:

    • Qt::TextFormat textFormat() const
    1. void setTextFormat(Qt::TextFormat)

    enum Qt::TextFormat

    这个枚举用于可以显示纯文本和富文本的小部件，例如QLabel。它用于决定文本字符串是否应被解释为一个或另一个。这通常是通过将一个枚举值传递给qtexted::setTextFormat() 函数来完成的。

    Constant	Value	Description
    Qt::PlainText	0	文本字符串被解释为纯文本字符串。
    Qt::RichText	1	文本字符串被解释为富文本字符串。有关富文本的定义，请参见支持的HTML子集。
    Qt::AutoText	2	如果Qt::mightBeRichText() 返回true，则文本字符串将解释为Qt::RichText，否则解释为Qt::PlainText。
    Qt::MarkdownText	3	文本字符串被解释为标记格式的文本。这个枚举值是在Qt5.14中添加的。

    

        QString str  = "<h1>Hello</h1> <i>Qt!</i>"
                             "<hr ><br>"
                             "<img src = 'file:///E:/Users/Desktop/qt5_particles.jpg'/>";
        label0->setText( str);
        label0->setTextFormat (Qt::PlainText);
    

11. textInteractionFlags: Qt::TextInteractionFlags 指定标签显示文本时应如何与用户输入交互

    如果标志包含Qt::LinksAccessibleByKeyboard，则焦点策略也会自动设置为Qt::StrongFocus。如果设置了Qt::TextSelectableByKeyboard，则焦点策略设置为Qt::ClickFocus。

    默认值为Qt::LinksAccessibleByMouse。

    Access functions:

    • Qt::TextInteractionFlags textInteractionFlags() const
    1. void setTextInteractionFlags(Qt::TextInteractionFlags flags)

    enum Qt::TextInteractionFlag
    flags Qt::TextInteractionFlags

    此枚举指定文本显示小部件如何响应用户输入。

    Constant	Value	Description
    Qt::NoTextInteraction	0	无法与文本交互。
    Qt::TextSelectableByMouse	1	可以使用鼠标选择文本，并使用关联菜单或标准键盘快捷键将其复制到剪贴板。
    Qt::TextSelectableByKeyboard	2	可以使用键盘上的光标键选择文本。将显示文本光标。
    Qt::LinksAccessibleByMouse	4	链接可以突出显示并用鼠标激活。
    Qt::LinksAccessibleByKeyboard	8	链接可以使用tab键集中并用enter键激活。
    Qt::TextEditable	16	文本完全可编辑。
    Qt::TextEditorInteraction	TextSelectableByMouse | TextSelectableByKeyboard| TextEditable	QTextEdit文本编辑器的默认值。
    Qt::TextBrowserInteraction	TextSelectableByMouse | LinksAccessibleByMouse | LinksAccessibleByKeyboard	QTextBrowser的默认值。

12. wordWrap: bool 标签的换行策略

    如果此属性为true，则标签文本将在必要的分词处进行包装；否则根本不会进行包装。

    默认情况下，将禁用自动换行。

    Access functions:

    • bool wordWrap() const
    • void setWordWrap(bool on)

    

        QString str  = "If this property is true then label text is wrapped where necessary at word-breaks; otherwise it is not wrapped at all.";
        label0->setText( str);
        label0->setWordWrap (true) ;
        label0->setAlignment (Qt::AlignTop);
    

公共函数

构造和析构

1. QLabel(const QString &text, QWidget *parent = nullptr, Qt::WindowFlags f = Qt::WindowFlags())
2. QLabel(QWidget *parent = nullptr, Qt::WindowFlags f = Qt::WindowFlags())
3. virtual ~QLabel()

属性相关

1. Qt::Alignment alignment() const
2. void setAlignment(Qt::Alignment)
3. bool hasSelectedText() const
4. int indent() const
5. void setIndent(int)
6. int margin() const
7. void setMargin(int)
8. bool openExternalLinks() const
9. void setOpenExternalLinks(bool open)
10. QPixmap pixmap(Qt::ReturnByValueConstant) const
11. void setPixmap(const QPixmap &)
12. bool hasScaledContents() const
13. void setScaledContents(bool)
14. QString selectedText() const
15. QString text() const
16. void setText(const QString &)
17. Qt::TextFormat textFormat() const
18. void setTextFormat(Qt::TextFormat)
19. Qt::TextInteractionFlags textInteractionFlags() const
20. void setTextInteractionFlags(Qt::TextInteractionFlags flags)
21. bool wordWrap() const
22. void setWordWrap(bool on)

其他

1. QWidget * buddy() const 返回好友

2. void setBuddy(QWidget *buddy) 设置好友控件
   当用户按下此标签指示的快捷键时，键盘焦点将转移到标签的好友小部件。
   伙伴机制仅适用于包含文本的qlabel，其中一个字符的前缀是与号“&”。此字符设置为快捷键。有关详细信息，请参阅QKeySequence::mnemonic() 文档（要显示实际的与号，请使用“&&”）。
   在对话框中，您可以创建两个数据输入小部件和每个小部件的一个标签，并设置几何图形布局，使每个标签正好位于其数据输入小部件（其“伙伴”）的左侧，例如:

   

    QApplication::setStyle (QStyleFactory::create ("fusion")); //使用fusion会始终显示下划线
    QLineEdit *nameEdit  = new QLineEdit(this);
    QLabel    *nameLabel = new QLabel("&Name:", this);
    nameLabel->setBuddy(nameEdit);
    QLineEdit *phoneEdit  = new QLineEdit(this);
    QLabel    *phoneLabel = new QLabel("&Phone:", this);
    phoneLabel->setBuddy(phoneEdit);
   

   在上面的代码中，当用户按Alt+N时，焦点跳转到Name字段，当用户按Alt+P时，焦点跳转到Phone字段。
   要取消设置以前设置的buddy，请在buddy设置为nullptr时调用此函数。

3. QMovie * movie() const 返回指向标签电影的指针，如果未设置电影，则返回nullptr

4. QPicture picture(Qt::ReturnByValueConstant) const 返回标签的图片

   以前，Qt提供了picture() 的一个版本，它通过指针返回图片。该版本现在已被弃用。要保持与旧代码的兼容性，可以显式区分by pointer函数和by value函数：

5. int selectionStart() const 返回标签中第一个选定字符的索引，如果未选择文本，则返回-1

   注意：标签上设置的textInteractionFlags需要包括TextSelectableByMouse或TextSelectableByKeyboard。

6. void setSelection(int start, int length) 从位置开始和长度字符中选择文本

   注意：标签上设置的textInteractionFlags需要包括TextSelectableByMouse或TextSelectableByKeyboard。

重写的公共函数

1. virtual int heightForWidth(int w) const override
2. virtual QSize minimumSizeHint() const override
3. virtual QSize sizeHint() const override

公共槽

1. void clear() 清空

2. void setMovie(QMovie *movie) 将标签内容设置为电影，并清除以前的任何内容

   标签并不拥有这部电影的所有权。好友快捷方式（如果有）也要被禁用。

   QMovie类是使用QImageReader播放电影的便利类。

   也就是显示没有声音的简单动画 *.gif 文件

   

       QLabel *widget0  = new QLabel(&w);
   
       QMovie *movie = new QMovie(&w);
       // ...\Examples\Qt-5.15.0\quick\imageelements\content\Uniflow_steam_engine.gif
       movie->setFileName ("E:/Users/Desktop/Uniflow_steam_engine.gif");
       movie->start ();
   
       qDebug() << QMovie::supportedFormats ();
   
       widget0->setMovie(movie);
       widget0->setScaledContents (true);  // 可以缩放动图
   

3. void setNum(double num) 将标签内容设置为纯文本，其中包含double num的文本表示形式

4. void setNum(int num) 将标签内容设置为包含整数num的文本表示形式的纯文本

   清除以前的任何内容。如果整数的字符串表示形式与标签的当前内容相同，则不执行任何操作。
   好友快捷方式（如果有）已禁用。

   

5. void setPicture(const QPicture &picture) 设置QPicture

6. void setPixmap(const QPixmap &) 设置QPixmap

7. void setText(const QString &) 属性相关

信号

1. void linkActivated(const QString &link)
2. void linkHovered(const QString &link)

重写的受保护的函数

1. virtual void changeEvent(QEvent *ev) override
2. virtual void contextMenuEvent(QContextMenuEvent *ev) override
3. virtual bool event(QEvent *e) override
4. virtual void focusInEvent(QFocusEvent *ev) override
5. virtual bool focusNextPrevChild(bool next) override
6. virtual void focusOutEvent(QFocusEvent *ev) override
7. virtual void keyPressEvent(QKeyEvent *ev) override
8. virtual void mouseMoveEvent(QMouseEvent *ev) override
9. virtual void mousePressEvent(QMouseEvent *ev) override
10. virtual void mouseReleaseEvent(QMouseEvent *ev) override
11. virtual void paintEvent(QPaintEvent *) override

参考

• Supported HTML Subset