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

QLabel ( QWidget * parent=0, const char * name=0, WFlags f=0 )
QLabel ( const char * text, QWidget * parent=0, const char * name=0, WFlags f=0 )
QLabel ( QWidget * buddy, const char * text, QWidget * parent, const char * name=0, WFlags f=0 )
~QLabel ()
const char* text () const
QPixmap* pixmap () const
QMovie* movie () const
int alignment () const
void setAlignment ( int )
int margin () const
void setMargin ( int )
bool autoResize () const
void setAutoResize ( bool )
virtual QSize sizeHint () const
void setBuddy ( QWidget * )
QWidget* buddy () const

Public Slots

void setText ( const char * )
void setPixmap ( const QPixmap & )
void setMovie ( const QMovie & )
void setNum ( int )
void setNum ( double )
void clear ()

Protected Members

virtual void drawContents ( QPainter * )

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.

Examples: tictac/tictac.cpp forever/forever.cpp movies/main.cpp xform/xform.cpp menu/menu.cpp pref/pref.cpp progress/progress.cpp cursor/cursor.cpp layout/layout.cpp qmag/qmag.cpp showimg/showimg.cpp widgets/widgets.cpp

Member Function Documentation

QLabel::QLabel ( QWidget * buddy, const char * text, QWidget * parent, const char * name=0, WFlags f=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.

QLabel::QLabel ( QWidget * parent=0, const char * name=0, WFlags f=0 )

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

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

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

QLabel::QLabel ( const char * text, QWidget * parent=0, const char * name=0, WFlags f=0 )

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

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

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

QLabel::~QLabel ()

Destroys the label.

int QLabel::alignment () const

Returns the alignment setting.

bool QLabel::autoResize () const

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

Auto-resizing is disabled by default.

QWidget * QLabel::buddy () const

Returns the buddy of this label.

void QLabel::clear () `[slot]`

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

void QLabel::drawContents ( QPainter * p ) `[virtual protected]`

Draws the label contents using the painter p.

Reimplemented from QFrame.

int QLabel::margin () const

Returns the margin of the label.

QMovie* QLabel::movie () const

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

Examples: widgets/widgets.cpp

QPixmap * QLabel::pixmap () const

Returns the label pixmap.

void QLabel::setAlignment ( int alignment )

Sets the alignment of the label contents and redraws itself.

The alignment is the bitwise OR of the following flags:

AlignLeft aligns to the left border.
AlignRight aligns to the right border.
AlignHCenter aligns horizontally centered.
AlignTop aligns to the top border.
AlignBottom aligns to the bottom border.
AlignVCenter aligns vertically centered
AlignCenter (= AlignHCenter | AlignVCenter)
ExpandTabs expands tabulators.
WordBreak enables automatic word breaking.

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

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

Examples: cursor/cursor.cpp layout/layout.cpp qmag/qmag.cpp widgets/widgets.cpp

void QLabel::setAutoResize ( bool enable )

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().

Examples: forever/forever.cpp

void QLabel::setBuddy ( QWidget * buddy )

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.

void QLabel::setMargin ( int margin )

Sets the margin of the label to margin pixels.

The margin 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 margin is negative (as it is by default), the label computes the margin as follows: If the frame width is zero, the effective margin becomes 0. If the frame style is greater than zero, the effective margin becomes half the width of the "x" character (of the widget's current font.

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

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

Examples: movies/main.cpp widgets/widgets.cpp

void QLabel::setMovie ( const QMovie & movie ) `[slot]`

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.

Examples: widgets/widgets.cpp

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

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.

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

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.

void QLabel::setPixmap ( const QPixmap & pixmap ) `[slot]`

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() and setAutoResize().

void QLabel::setText ( const char * text ) `[slot]`

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.

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

Examples: forever/forever.cpp xform/xform.cpp pref/pref.cpp cursor/cursor.cpp layout/layout.cpp qmag/qmag.cpp widgets/widgets.cpp

QSize QLabel::sizeHint () const `[virtual]`

Returns a size which fits the contents of the label.

Bugs and limitations:

Does not work well with the WordBreak flag

Examples: pref/pref.cpp layout/layout.cpp widgets/widgets.cpp

Reimplemented from QWidget.

const char * QLabel::text () const

Returns the label text.