Contents

KUrlLabel Class

A drop-in replacement for QLabel that displays hyperlinks. More...

Header: #include <KUrlLabel>
CMake: find_package(KF6 REQUIRED COMPONENTS WidgetsAddons)
target_link_libraries(mytarget PRIVATE KF6::WidgetsAddons)
Inherits: QLabel

Properties

Public Functions

KUrlLabel(QWidget *parent = nullptr)
KUrlLabel(const QString &url, const QString &text = QString(), QWidget *parent = nullptr)
const QPixmap *alternatePixmap() const
bool isFloatEnabled() const
bool isGlowEnabled() const
QString tipText() const
QString url() const
bool useCursor() const
bool useTips() const

Public Slots

void setAlternatePixmap(const QPixmap &pixmap)
void setFloatEnabled(bool do_float = true)
void setGlowEnabled(bool glow = true)
void setHighlightedColor(const QColor &highcolor)
void setHighlightedColor(const QString &highcolor)
void setSelectedColor(const QColor &color)
void setSelectedColor(const QString &color)
void setTipText(const QString &tip)
void setUnderline(bool on = true)
void setUrl(const QString &url)
void setUseCursor(bool on, QCursor *cursor = nullptr)
void setUseTips(bool on = true)

Signals

void enteredUrl()
void leftClickedUrl()
void leftUrl()
void middleClickedUrl()
void rightClickedUrl()

Detailed Description

KUrlLabel is a drop-in replacement for QLabel that handles text in a fashion similar to how an HTML widget handles hyperlinks. The text can be underlined (or not) and set to different colors. It can also "glow" (cycle colors) when the mouse passes over it.

KUrlLabel also provides signals for several events, including the mouse leaving and entering the text area and all forms of mouse clicking.

By default KUrlLabel accepts focus. When focused, standard focus rectangle is displayed as in HTML widget. Pressing Enter key accepts the focused label.

A typical usage would be something like so:

KUrlLabel *address = new KUrlLabel(this);
address->setText("My homepage");
address->setUrl("http://www.home.com/~me");
connect(address, &KUrlLabel::leftClickedUrl, this, [this](cont QString &url) { processMyUrl(url); };

In this example, the text "My homepage" would be displayed as blue, underlined text. When the mouse passed over it, it would "glow" red. When the user clicks on the text, the signal leftClickedUrl() would be emitted with "http://www.home.com/~me" as its argument.

KUrlLabel Widget

Property Documentation

alternatePixmap : QPixmap

Access functions:

const QPixmap *alternatePixmap() const
void setAlternatePixmap(const QPixmap &pixmap)

floatEnabled : bool

Access functions:

bool isFloatEnabled() const
void setFloatEnabled(bool do_float = true)

glowEnabled : bool

Access functions:

bool isGlowEnabled() const
void setGlowEnabled(bool glow = true)

tipText : QString

Access functions:

QString tipText() const
void setTipText(const QString &tip)

url : QString

Access functions:

QString url() const
void setUrl(const QString &url)

useCursor : bool

Access functions:

bool useCursor() const
void setUseCursor(bool on, QCursor *cursor = nullptr)

useTips : bool

Access functions:

bool useTips() const
void setUseTips(bool on = true)

Member Function Documentation

[explicit] KUrlLabel::KUrlLabel(QWidget *parent = nullptr)

Default constructor.

Use setUrl() and setText() or QListView::setPixmap() to set the resp. properties.

[explicit] KUrlLabel::KUrlLabel(const QString &url, const QString &text = QString(), QWidget *parent = nullptr)

Convenience constructor.

url is the URL emitted when the label is clicked.

text is the displayed string. If it's equal to QString() the url will be used instead.

parent Passed to lower level constructor

@p parent and @p name are passed to QLabel, which in turn passes them further down

const QPixmap *KUrlLabel::alternatePixmap() const

Returns the alternate pixmap (may be a null pointer if none was set)

Note: Getter function for property alternatePixmap.

See also setAlternatePixmap().

[signal] void KUrlLabel::enteredUrl()

Emitted when the mouse has passed over the label.

bool KUrlLabel::isFloatEnabled() const

This feature is very similar to the "glow" feature in that the color of the label switches to the selected color when the cursor passes over it. In addition, underlining is turned on for as long as the mouse is overhead. Note that if "glow" and underlining are both already turned on, this feature will have no visible effect.

Note: Getter function for property floatEnabled.

bool KUrlLabel::isGlowEnabled() const

When this is on, the text will switch to the selected color whenever the mouse passes over it.

Note: Getter function for property glowEnabled.

[signal] void KUrlLabel::leftClickedUrl()

Emitted when the user clicked the left mouse button on this label.

[signal] void KUrlLabel::leftUrl()

Emitted when the mouse is no longer over the label.

[signal] void KUrlLabel::middleClickedUrl()

Emitted when the user clicked the left mouse button on this label.

[signal] void KUrlLabel::rightClickedUrl()

Emitted when the user clicked the right mouse button on this label.

[slot] void KUrlLabel::setAlternatePixmap(const QPixmap &pixmap)

Sets the "alt" pixmap.

This pixmap will be displayed when the cursor passes over the label. The effect is similar to the trick done with 'onMouseOver' in javascript.

Note: Setter function for property alternatePixmap.

See also alternatePixmap().

[slot] void KUrlLabel::setFloatEnabled(bool do_float = true)

Turns on or off the "float" feature.

This feature is very similar to the "glow" feature in that the color of the label switches to the selected color when the cursor passes over it. In addition, underlining is turned on for as long as the mouse is overhead. Note that if "glow" and underlining are both already turned on, this feature will have no visible effect. By default, it is false.

Note: Setter function for property floatEnabled.

See also isFloatEnabled().

[slot] void KUrlLabel::setGlowEnabled(bool glow = true)

Turns on or off the "glow" feature.

When this is on, the text will switch to the selected color whenever the mouse passes over it. By default, it is true.

Note: Setter function for property glowEnabled.

See also isGlowEnabled().

[slot] void KUrlLabel::setHighlightedColor(const QColor &highcolor)

Sets the highlight color.

This is the default foreground color (non-selected). By default, it is blue.

[slot] void KUrlLabel::setHighlightedColor(const QString &highcolor)

This is an overloaded version for convenience.

See also setHighlightedColor().

[slot] void KUrlLabel::setSelectedColor(const QColor &color)

Sets the selected color.

This is the color the text will change to when either a mouse passes over it and "glow" mode is on or when it is selected (clicked). By default, it is red.

[slot] void KUrlLabel::setSelectedColor(const QString &color)

This is an overloaded version for convenience.

See also setSelectedColor().

[slot] void KUrlLabel::setTipText(const QString &tip)

Specifies what text to display when tooltips are turned on.

If this is not used, the tip will default to the URL.

Note: Setter function for property tipText.

See also tipText() and setUseTips().

[slot] void KUrlLabel::setUnderline(bool on = true)

Turns on or off the underlining.

When this is on, the text will be underlined. By default, it is true.

[slot] void KUrlLabel::setUrl(const QString &url)

Sets the URL for this label to url.

Note: Setter function for property url.

See also url.

[slot] void KUrlLabel::setUseCursor(bool on, QCursor *cursor = nullptr)

Turns the custom cursor feature on or off.

When this is on, the cursor will change to a custom cursor (default is a "pointing hand") whenever the cursor passes over the label. By default, it is on.

on whether a custom cursor should be displayed.

cursor the custom cursor. A null pointer indicates the default "hand cursor".

Note: Setter function for property useCursor.

See also useCursor().

[slot] void KUrlLabel::setUseTips(bool on = true)

Turns on or off the tool tip feature.

When this is on, the URL will be displayed as a tooltip whenever the mouse passes passes over it. By default, it is false.

Note: Setter function for property useTips.

See also useTips().

QString KUrlLabel::tipText() const

Returns the current tooltip text.

Note: Getter function for property tipText.

See also setTipText().

QString KUrlLabel::url() const

Returns the URL.

Note: Getter function for property url.

See also setUrl().

bool KUrlLabel::useCursor() const

Returns true if the cursor will change while over the URL.

Note: Getter function for property useCursor.

See also setUseCursor().

bool KUrlLabel::useTips() const

Returns true if a tooltip will be displayed.

Note: Getter function for property useTips.

See also setUseTips() and setTipText().