Qt Toolkit - QLabel Class

# 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.

See also: QLineEdit, QMovie and GUI Design Handbook: 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.

See also: setText() and setBuddy().

### 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.

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

### bool QLabel::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.

### 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.

See also: setMargin().

### 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.

See also: setPixmap().

### 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.

See also: label() and setText().

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

### 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.

See also: setAutoResize().

### 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.

See also: setAutoResize().

### 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.

See also: setText().

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.

It was generated from the following files:

- qlabel.h: 1998/08/21
- qlabel.cpp: 1999/01/13