Qt logo

QLabel Class Reference


The QLabel widget displays a static text or pixmap. More...

#include <qlabel.h>

Inherits QFrame.

List of all member functions.

Public Members

Public Slots

Protected Members


Detailed Description

The QLabel widget displays a static text or pixmap.

A label is a static text or pixmap field.

It can have a frame (since QLabel inherits QFrame) and a "buddy" and an accelerator for moving keyboard focus to the buddy.

The contents of a label can be specified as a normal text, as a numeric value (which is internally converted to a text) or, as a pixmap. If the label is normal text and one of the letters is prefixed with '&', you can also specify a buddy for the label:

     QLineEdit * phone = new QLineEdit( this, "phone number" );
     QLabel * phoneLabel = new QLabel( phone, "&Phone", this );

In this example, keyboard focus is transferred to the label's buddy (the QLineEdit) when the user presses Alt-P. This is handy for many dialogs. You can also use the setBuddy() function to accomplish the same means.

A label can be aligned in many different ways. The alignment setting specifies where to position the contents relative to the frame rectangle. See setAlignment() for a description of the alignment flags.

Enabling auto-resizing make the label resize itself whenever the contents change. The top left corner does not move.

This code sets up a sunken panel with a two-line text in the bottom right corner:

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

Both lines are flush with the right side of the label.

A label may also be used to provide a slightly larger amount of information, for example a few lines help text in a dialog. For this reason, QLabel also supports rich text rendering. The available styles are defined in the default stylesheet QStyleSheet::defaultSheet(). Usually the label autodetects from the set text whether rich text rendering is required. The format, however, can also be specified directly with setTextFormat(). Note that buddies will not work yet with rich text labels since there's not way to specify the accelerator (yet).

See also: QLineEdit, QMovie, QTextView and GUI Design Handbook: Label

Examples: tabdialog/tabdialog.cpp cursor/cursor.cpp layout/layout.cpp popup/popup.cpp menu/menu.cpp progress/progress.cpp qmag/qmag.cpp movies/main.cpp customlayout/main.cpp


Member Function Documentation

QLabel::QLabel(QWidget*buddy, constQString&text, QWidget*parent, constchar*name=0, WFlagsf=0)

Constructs a label with an accelerator key.

The parent, name and f arguments are passed to the QFrame constructor. Note that the parent argument does not default to 0.

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

    QLineEdit *name    = new QLineEdit( this );
    QLabel    *name_l  = new QLabel( name, "&Name:", this );
    QLineEdit *phone   = new QLineEdit( this );
    QLabel    *phone_l = new QLabel( phone, "&Phone:", this );
    // geometry management 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.

See also: setText() and setBuddy().

QLabel::QLabel(QWidget*parent, constchar*name=0, WFlagsf=0)

Constructs an empty label which is left-aligned, vertically centered, has an automatic indent and with manual resizing.

The parent, name and f arguments are passed to the QFrame constructor.

See also: setAlignment(), setFrameStyle(), setIndent() and setAutoResize().

QLabel::QLabel(constQString&text, QWidget*parent, constchar*name=0, WFlagsf=0)

Constructs a label with a text. The label is left-aligned, vertically centered, has an automatic indent and with manual resizing.

The parent, name and f arguments are passed to the QFrame constructor.

See also: setAlignment(), setFrameStyle(), setIndent() and setAutoResize().

QLabel::~QLabel()

Destroys the label.

intQLabel::alignment()const

Returns the alignment setting.

The default alignment is AlignLeft | AlignVCenter | ExpandTabs if the label doesn't have a buddy and AlignLeft | AlignVCenter | ExpandTabs | ShowPrefix if the label has a buddy.

See also: setAlignment().

boolQLabel::autoResize()const

Returns TRUE if auto-resizing is enabled, or FALSE if auto-resizing is disabled.

Auto-resizing is disabled by default.

See also: setAutoResize().

QWidget*QLabel::buddy()const

Returns the buddy of this label.

voidQLabel::clear() [slot]

Clears the label. Equivalent with setText( "" ).

voidQLabel::drawContents(QPainter*p) [virtualprotected]

Draws the label contents using the painter p.

Reimplemented from QFrame.

voidQLabel::drawContentsMask(QPainter*p) [virtualprotected]

Draws the label contents mask using the painter p. Used only in transparent mode.

See also: QWidget::setAutoMask();.

Reimplemented from QFrame.

intQLabel::heightForWidth(intw)const [virtual]

Reimplemented for rich text labels and WordBreak.

Reimplemented from QWidget.

intQLabel::indent()const

Returns the indent of the label.

See also: setIndent().

QMovie*QLabel::movie()const

Returns the QMovie currently displaying in the label, or 0 if none has been set.

See also: setMovie() and unsetMovie().

QPixmap*QLabel::pixmap()const

Returns the label pixmap.

See also: setPixmap().

voidQLabel::setAlignment(intalignment) [virtual]

Sets the alignment of the label contents and redraws itself.

The alignment is the bitwise OR of the following flags:

If the label has a buddy, ShowPrefix is forced to TRUE.

See also: alignment(), setBuddy() and setText().

Examples: cursor/cursor.cpp layout/layout.cpp popup/popup.cpp qmag/qmag.cpp customlayout/main.cpp

voidQLabel::setAutoResize(boolenable) [virtual]

Enables auto-resizing if enable is TRUE, or disables it if enable is FALSE.

When auto-resizing is enabled, the label will resize itself whenever the contents change. The top left corner is not moved.

See also: autoResize() and adjustSize().

voidQLabel::setBuddy(QWidget*buddy) [virtual]

Sets the buddy of this label to buddy.

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

See also: label() and setText().

Examples: layout/layout.cpp

voidQLabel::setIndent(intindent)

Sets the indent of the label to indent pixels.

The indent applies to the left edge if alignment() is AlignLeft, to the right edge if alignment() is AlignRight, to the top edge if alignment() is AlignTop, and to to the bottom edge if alignment() is AlignBottom.

If indent is negative (as it is by default), the label computes the indent as follows: If the frame width is zero, the effective indent becomes 0. If the frame style is greater than zero, the effective indent becomes half the width of the "x" character (of the widget's current font.

Setting a non-negative indent gives the specified indent in pixels.

See also: indent(), frameWidth() and font().

Examples: movies/main.cpp

voidQLabel::setMovie(constQMovie&movie) [virtualslot]

Sets a QMovie to display in the label, or removes any existing movie if the given movie QMovie::isNull().

Any current pixmap or text label is cleared.

If the label has a buddy, the accelerator is disabled since the movie doesn't contain any suitable character.

See also: unsetMovie().

voidQLabel::setNum(doublenum) [virtualslot]

Sets the label contents to num (converts it to text) and redraws the contents.

If the label has a buddy, the accelerator is disabled since the number doesn't contain any suitable character.

The label resizes itself if auto-resizing is enabled.

See also: setAutoResize().

voidQLabel::setNum(intnum) [virtualslot]

Sets the label contents to num (converts it to text) and redraws the contents.

If the label has a buddy, the accelerator is disabled since the number doesn't contain any suitable character.

The label resizes itself if auto-resizing is enabled. Nothing happens if num reads the same as the current label.

See also: setAutoResize().

voidQLabel::setPixmap(constQPixmap&pixmap) [virtualslot]

Sets the label contents to pixmap and redraws the contents.

If the label has a buddy, the accelerator is disabled since the pixmap doesn't contain any suitable character.

The label resizes itself if auto-resizing is enabled. Nothing happens if pixmap is the same as the current label.

See also: pixmap(), setText(), setTextFormat() and setAutoResize().

voidQLabel::setText(constQString&text) [virtualslot]

Sets the label contents to text, updates the optional accelerator and redraws the contents.

The label resizes itself if auto-resizing is enabled. Nothing happens if text is the same as the current label.

text may be interpreted either as plain text or as rich text, depending on the textFormat(). The default setting is AutoText, i.e. the label autodetects the format from text. If the format is RichText, the label uses the default mime source factory to resolve references to images. See QMimeSourceFactory::defaultFactory() for details.

Note that a label is only useful for rather small documents with one or maximal two lines of text. If you need to display larger documents, a QTextView is the widget of choice. It will flicker less on resize and can also provide a scrollbar if necessary.

See also: text(), setTextFormat(), setPixmap(), setAutoResize() and QTextView.

Examples: cursor/cursor.cpp layout/layout.cpp popup/popup.cpp qmag/qmag.cpp customlayout/main.cpp

voidQLabel::setTextFormat(Qt::TextFormatformat)

Sets the text format to format. Possible choices are

QSizeQLabel::sizeHint()const [virtual]

Returns a size which fits the contents of the label.

Bugs and limitations:

Examples: layout/layout.cpp

Reimplemented from QWidget.

QSizePolicyQLabel::sizePolicy()const [virtual]

Specifies that this widget may stretch horizontally and vertically beyond the sizeHint().

Reimplemented from QWidget.

QStringQLabel::text()const

Returns the label text. This may be either plain text or a small rich text document.

See also: textFormat(), setText() and setTextFormat().

Qt::TextFormatQLabel::textFormat()const

Returns the current text format.

See also: setTextFormat().


Search the documentation, FAQ, qt-interest archive and more (uses www.troll.no):


This file is part of the Qt toolkit, copyright © 1995-99 Troll Tech, all rights reserved.


Copyright 1999 Troll TechTrademarks
Qt version 2.0.2