Contents

• Properties
• Public Functions
• Reimplemented Public Functions
• Public Slots
• Signals
• Reimplemented Protected Functions
• Detailed Description

Detailed Description

TheQLabel widget provides a text or image display.

QLabel is used for displaying text or an image. No user interaction functionality is provided. The visual appearance of the label can be configured in various ways, and it can be used for specifying a focus mnemonic key for another widget.

AQLabel can contain any of the following content types:

Warning: When passing aQString to the constructor or callingsetText(), make sure to sanitize your input, asQLabel tries to guess whether it displays the text as plain text or as rich text. You may want to callsetTextFormat() explicitly, e.g. in case you expect the text to be in plain format but cannot control the text source (for instance when displaying data loaded from the Web).

When the content is changed using any of these functions, any previous content is cleared.

By default, labels displayleft-aligned, vertically-centered text and images, where any tabs in the text to be displayed areautomatically expanded. However, the look of aQLabel can be adjusted and fine-tuned in several ways.

The positioning of the content within theQLabel widget area can be tuned withsetAlignment() andsetIndent(). Text content can also wrap lines along word boundaries withsetWordWrap(). For example, this code sets up a sunken panel with a two-line text in the bottom right corner (both lines being flush with the right side of the label):

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

The properties and functionsQLabel inherits fromQFrame can also be used to specify the widget frame to be used for any given label.

AQLabel is often used as a label for an interactive widget. For this useQLabel provides a useful mechanism for adding an mnemonic (seeQKeySequence) that will set the keyboard focus to the other widget (called theQLabel's "buddy"). For example:

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

In this example, keyboard focus is transferred to the label's buddy (theQLineEdit) when the user presses Alt+P. If the buddy was a button (inheriting fromQAbstractButton), triggering the mnemonic would emulate a button click.

	A label shown in theMacintosh widget style.
	A label shown in thePlastique widget style.
	A label shown in theWindows XP widget style.

Property Documentation

alignment :Qt::Alignment

This property holds the alignment of the label's contents.

By default, the contents of the label are left-aligned and vertically-centered.

Access functions:

See alsotext.

hasSelectedText : constbool

This property holds whether there is any text selected.

hasSelectedText() returns true if some or all of the text has been selected by the user; otherwise returns false.

By default, this property is false.

Note: ThetextInteractionFlags set on the label need to include either TextSelectableByMouse or TextSelectableByKeyboard.

This property was introduced in Qt 4.7.

Access functions:

See alsoselectedText().

indent :int

This property holds the label's text indent in pixels.

If a label displays text, the indent applies to the left edge ifalignment() isQt::AlignLeft, to the right edge ifalignment() isQt::AlignRight, to the top edge ifalignment() isQt::AlignTop, and to to the bottom edge ifalignment() isQt::AlignBottom.

If indent is negative, or if no indent has been set, the label computes the effective indent as follows: IfframeWidth() is 0, the effective indent becomes 0. IfframeWidth() is greater than 0, the effective indent becomes half the width of the "x" character of the widget's currentfont().

By default, the indent is -1, meaning that an effective indent is calculating in the manner described above.

Access functions:

See alsoalignment,margin,frameWidth(), andfont().

margin :int

This property holds the width of the margin.

The margin is the distance between the innermost pixel of the frame and the outermost pixel of contents.

The default margin is 0.

Access functions:

See alsoindent.

openExternalLinks :bool

Specifies whetherQLabel should automatically open links usingQDesktopServices::openUrl() instead of emitting thelinkActivated() signal.

Note: ThetextInteractionFlags set on the label need to include either LinksAccessibleByMouse or LinksAccessibleByKeyboard.

The default value is false.

This property was introduced in Qt 4.2.

Access functions:

See alsotextInteractionFlags().

pixmap :QPixmap

This property holds the label's pixmap.

If no pixmap has been set this will return 0.

Setting the pixmap clears any previous content. The buddy shortcut, if any, is disabled.

Access functions:

scaledContents :bool

This property holds whether the label will scale its contents to fill all available space.

When enabled and the label shows a pixmap, it will scale the pixmap to fill the available space.

This property's default is false.

Access functions:

selectedText : constQString

This property holds the selected text.

If there is no selected text this property's value is an empty string.

By default, this property contains an empty string.

Note: ThetextInteractionFlags set on the label need to include either TextSelectableByMouse or TextSelectableByKeyboard.

This property was introduced in Qt 4.7.

Access functions:

See alsohasSelectedText().

text :QString

This property holds the label's text.

If no text has been set this will return an empty string. Setting the text clears any previous content.

The text will be interpreted either as plain text or as rich text, depending on the text format setting; seesetTextFormat(). The default setting isQt::AutoText; i.e.QLabel will try to auto-detect the format of the text set.

If a buddy has been set, the buddy mnemonic key is updated from the new text.

Note thatQLabel is well-suited to display small rich text documents, such as small documents that get their document specific settings (font, text color, link color) from the label's palette and font properties. For large documents, useQTextEdit in read-only mode instead.QTextEdit can also provide a scroll bar when necessary.

Note:This function enables mouse tracking iftext contains rich text.

Access functions:

See alsosetTextFormat(),setBuddy(), andalignment.

textFormat :Qt::TextFormat

This property holds the label's text format.

See theQt::TextFormat enum for an explanation of the possible options.

The default format isQt::AutoText.

Access functions:

See alsotext().

textInteractionFlags :Qt::TextInteractionFlags

Specifies how the label should interact with user input if it displays text.

If the flags containQt::LinksAccessibleByKeyboard the focus policy is also automatically set toQt::StrongFocus. IfQt::TextSelectableByKeyboard is set then the focus policy is set toQt::ClickFocus.

The default value isQt::LinksAccessibleByMouse.

This property was introduced in Qt 4.2.

Access functions:

wordWrap :bool

This property holds the label's word-wrapping policy.

If this property is true then label text is wrapped where necessary at word-breaks; otherwise it is not wrapped at all.

By default, word wrap is disabled.

Access functions:

See alsotext.

Member Function Documentation

QLabel::QLabel(QWidget * parent = 0,Qt::WindowFlags f = 0)

Constructs an empty label.

Theparent and widget flagf, arguments are passed to theQFrame constructor.

See alsosetAlignment(),setFrameStyle(), andsetIndent().

QLabel::QLabel(constQString & text,QWidget * parent = 0,Qt::WindowFlags f = 0)

Constructs a label that displays the text,text.

Theparent and widget flagf, arguments are passed to theQFrame constructor.

See alsosetText(),setAlignment(),setFrameStyle(), andsetIndent().

QLabel::~QLabel()

Destroys the label.

QWidget * QLabel::buddy() const

Returns this label's buddy, or 0 if no buddy is currently set.

See alsosetBuddy().

[virtual protected]void QLabel::changeEvent(QEvent * ev)

Reimplemented fromQWidget::changeEvent().

[slot]void QLabel::clear()

Clears any label contents.

[virtual protected]void QLabel::contextMenuEvent(QContextMenuEvent * ev)

Reimplemented fromQWidget::contextMenuEvent().

[virtual protected]bool QLabel::event(QEvent * e)

Reimplemented fromQObject::event().

[virtual protected]void QLabel::focusInEvent(QFocusEvent * ev)

Reimplemented fromQWidget::focusInEvent().

[virtual protected]bool QLabel::focusNextPrevChild(bool next)

Reimplemented fromQWidget::focusNextPrevChild().

[virtual protected]void QLabel::focusOutEvent(QFocusEvent * ev)

Reimplemented fromQWidget::focusOutEvent().

[virtual]int QLabel::heightForWidth(int w) const

Reimplemented fromQWidget::heightForWidth().

[virtual protected]void QLabel::keyPressEvent(QKeyEvent * ev)

Reimplemented fromQWidget::keyPressEvent().

[signal]void QLabel::linkActivated(constQString & link)

This signal is emitted when the user clicks a link. The URL referred to by the anchor is passed inlink.

This function was introduced in Qt 4.2.

See alsolinkHovered().

[signal]void QLabel::linkHovered(constQString & link)

This signal is emitted when the user hovers over a link. The URL referred to by the anchor is passed inlink.

This function was introduced in Qt 4.2.

See alsolinkActivated().

[virtual]QSize QLabel::minimumSizeHint() const

Reimplemented fromQWidget::minimumSizeHint().

[virtual protected]void QLabel::mouseMoveEvent(QMouseEvent * ev)

Reimplemented fromQWidget::mouseMoveEvent().

[virtual protected]void QLabel::mousePressEvent(QMouseEvent * ev)

Reimplemented fromQWidget::mousePressEvent().

[virtual protected]void QLabel::mouseReleaseEvent(QMouseEvent * ev)

Reimplemented fromQWidget::mouseReleaseEvent().

QMovie * QLabel::movie() const

Returns a pointer to the label's movie, or 0 if no movie has been set.

See alsosetMovie().

[virtual protected]void QLabel::paintEvent(QPaintEvent *)

Reimplemented fromQWidget::paintEvent().

constQPicture * QLabel::picture() const

Returns the label's picture or 0 if the label doesn't have a picture.

See alsosetPicture().

int QLabel::selectionStart() const

selectionStart() returns the index of the first selected character in the label or -1 if no text is selected.

Note: ThetextInteractionFlags set on the label need to include either TextSelectableByMouse or TextSelectableByKeyboard.

This function was introduced in Qt 4.7.

See alsoselectedText().

void QLabel::setBuddy(QWidget * buddy)

Sets this label's buddy tobuddy.

When the user presses the shortcut key indicated by this label, the keyboard focus is transferred to the label's buddy widget.

The buddy mechanism is only available for QLabels that contain text in which one character is prefixed with an ampersand, '&'. This character is set as the shortcut key. See theQKeySequence::mnemonic() documentation for details (to display an actual ampersand, use '&&').

In a dialog, you might create two data entry widgets and a label for each, and set up the geometry layout so each label is just to the left of its data entry widget (its "buddy"), for example:

QLineEdit*nameEd=newQLineEdit(this);QLabel*nameLb=newQLabel("&Name:",this);nameLb->setBuddy(nameEd);QLineEdit*phoneEd=newQLineEdit(this);QLabel*phoneLb=newQLabel("&Phone:",this);phoneLb->setBuddy(phoneEd);// (layout setup not shown)

With the code above, the focus jumps to the Name field when the user presses Alt+N, and to the Phone field when the user presses Alt+P.

To unset a previously set buddy, call this function withbuddy set to 0.

See alsobuddy(),setText(),QShortcut, andsetAlignment().

[slot]void QLabel::setMovie(QMovie * movie)

Sets the label contents tomovie. Any previous content is cleared. The label does NOT take ownership of the movie.

The buddy shortcut, if any, is disabled.

See alsomovie() andsetBuddy().

[slot]void QLabel::setNum(int num)

Sets the label contents to plain text containing the textual representation of integernum. Any previous content is cleared. Does nothing if the integer's string representation is the same as the current contents of the label.

The buddy shortcut, if any, is disabled.

See alsosetText(),QString::setNum(), andsetBuddy().

[slot]void QLabel::setNum(double num)

This is an overloaded function.

Sets the label contents to plain text containing the textual representation of doublenum. Any previous content is cleared. Does nothing if the double's string representation is the same as the current contents of the label.

The buddy shortcut, if any, is disabled.

See alsosetText(),QString::setNum(), andsetBuddy().

[slot]void QLabel::setPicture(constQPicture & picture)

Sets the label contents topicture. Any previous content is cleared.

The buddy shortcut, if any, is disabled.

See alsopicture() andsetBuddy().

void QLabel::setSelection(int start,int length)

Selects text from positionstart and forlength characters.

Note: ThetextInteractionFlags set on the label need to include either TextSelectableByMouse or TextSelectableByKeyboard.

This function was introduced in Qt 4.7.

See alsoselectedText().

[virtual]QSize QLabel::sizeHint() const

Reimplemented fromQWidget::sizeHint().