KWidgetsAddons

ksqueezedtextlabel.h
1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 2000 Ronny Standtke <Ronny.Standtke@gmx.de>
4
5 SPDX-License-Identifier: LGPL-2.0-only
6*/
7
8#ifndef KSQUEEZEDTEXTLABEL_H
9#define KSQUEEZEDTEXTLABEL_H
10
11#include <QLabel>
12#include <kwidgetsaddons_export.h>
13#include <memory>
14
15/**
16 * @class KSqueezedTextLabel ksqueezedtextlabel.h KSqueezedTextLabel
17 *
18 * @short A replacement for QLabel that squeezes its text into the label
19 *
20 * If the text is too long to fit into the label it is divided into
21 * remaining left and right parts which are separated by three dots.
22 * Hovering the mouse over the label shows the full text in a tooltip.
23 *
24 * Example:
25 * http://www.kde.org/documentation/index.html could be squeezed to
26 * http://www.kde...ion/index.html
27 *
28 * \image html ksqueezedtextlabel.png "KSqueezedTextLabel Widget"
29 *
30 * To change the position of the elision mark to the left or right end
31 * of the text, use setTextElideMode().
32 *
33 * @anchor non-virtual-warning
34 * @note Several functions of KSqueezedTextLabel (indicated by a warning
35 * in their description) reimplement non-virtual functions of QLabel.
36 * Therefore, you may need to cast the object to KSqueezedTextLabel in
37 * some situations:
38 * \Example
39 * \code
40 * KSqueezedTextLabel* squeezed = new KSqueezedTextLabel("text", parent);
41 * QLabel* label = squeezed;
42 * label->setText("new text"); // this will not work
43 * squeezed->setText("new text"); // works as expected
44 * static_cast<KSqueezedTextLabel*>(label)->setText("new text"); // works as expected
45 * \endcode
46 *
47 * @author Ronny Standtke <Ronny.Standtke@gmx.de>
48 */
49// TODO KF6:
50// - make more functions virtual (to benefit subclasses of KSqueezedTextLabel)
51// - try to eliminate need for non-virtual-warning (to benefit use as QLabel),
52// see https://phabricator.kde.org/D7164 for some ideas/considerations
53class KWIDGETSADDONS_EXPORT KSqueezedTextLabel : public QLabel
54{
55 Q_OBJECT
56 Q_PROPERTY(Qt::TextElideMode textElideMode READ textElideMode WRITE setTextElideMode)
57 Q_PROPERTY(int indent READ indent WRITE setIndent)
58 Q_PROPERTY(int margin READ margin WRITE setMargin)
59
60public:
61 /**
62 * Default constructor.
63 * @param parent the label's parent object
64 */
65 explicit KSqueezedTextLabel(QWidget *parent = nullptr);
66
67 /**
68 * @param text the text that will be displayed
69 * @param parent the label's parent object
70 */
71 explicit KSqueezedTextLabel(const QString &text, QWidget *parent = nullptr);
72
73 ~KSqueezedTextLabel() override;
74
75 /**
76 * @return the label's minimum size, where the horizontal component
77 * will be -1 to indicate the label's ability to shrink its width
78 * by squeezing the text
79 */
80 QSize minimumSizeHint() const override;
81
82 /**
83 * @return the label's preferred size, which is wide enough
84 * to display the text without squeezing it
85 */
86 QSize sizeHint() const override;
87
88 /**
89 * Sets the indentation of the label.
90 *
91 * @param indent the amount of indentation in pixels
92 *
93 * Reimplementation of QLabel::setIndent().
94 *
95 * @warning The corresponding function in the base class is not virtual.
96 * Therefore make sure to call this function on objects of type KSqueezedTextLabel,
97 * as shown in the @ref non-virtual-warning "example in the class description".
98 *
99 * @since 5.39
100 */
101 void setIndent(int indent);
102
103 /**
104 * Sets the margin of the label.
105 *
106 * @param margin the margin size in pixels
107 *
108 * Reimplementation of QLabel::setMargin().
109 *
110 * @warning The corresponding function in the base class is not virtual.
111 * Therefore make sure to call this function on objects of type KSqueezedTextLabel,
112 * as shown in the @ref non-virtual-warning "example in the class description".
113 *
114 * @since 5.39
115 */
116 void setMargin(int margin);
117
118 /**
119 * Overridden for internal reasons; the API remains unaffected.
120 */
121 virtual void setAlignment(Qt::Alignment);
122
123 /**
124 * @return the text elide mode
125 */
126 Qt::TextElideMode textElideMode() const;
127
128 /**
129 * Sets the text elide mode.
130 * @param mode The text elide mode.
131 */
132 void setTextElideMode(Qt::TextElideMode mode);
133
134 /**
135 * @return the full text set via setText()
136 *
137 * @since 4.4
138 */
139 QString fullText() const;
140
141 /**
142 * @returns true if the text displayed is currently squeezed,
143 * i.e. the original text does not fit inside the space available
144 * and elide mode is set to a value other than Qt::ElideNone.
145 *
146 * @since 5.38
147 */
148 bool isSqueezed() const;
149
150 /**
151 * @return the rectangle to squeeze the text into
152 *
153 * Reimplementation of QLabel::contentsRect().
154 *
155 * @warning The corresponding function in the base class is not virtual.
156 * Therefore make sure to call this function on objects of type KSqueezedTextLabel,
157 * as shown in the @ref non-virtual-warning "example in the class description".
158 *
159 * @since 5.39
160 */
161 QRect contentsRect() const;
162
163public Q_SLOTS:
164 /**
165 * Sets the text.
166 * @param text The new text.
167 *
168 * Reimplementation of QLabel::setText().
169 *
170 * @warning The corresponding function in the base class is not virtual.
171 * Therefore make sure to call this function on objects of type KSqueezedTextLabel,
172 * as shown in the @ref non-virtual-warning "example in the class description".
173 */
174 void setText(const QString &text);
175
176 /**
177 * Clears the text.
178 *
179 * Reimplementation of QLabel::clear().
180 *
181 * @warning The corresponding function in the base class is not virtual.
182 * Therefore make sure to call this function on objects of type KSqueezedTextLabel,
183 * as shown in the @ref non-virtual-warning "example in the class description".
184 */
185 void clear();
186
187protected:
188 /**
189 * \reimp
190 */
191 void mouseReleaseEvent(QMouseEvent *) override;
192
193 /**
194 * Called when widget is resized
195 */
196 void resizeEvent(QResizeEvent *) override;
197
198 /**
199 * \reimp
200 */
201 void contextMenuEvent(QContextMenuEvent *) override;
202
203 /**
204 * does the dirty work
205 */
206 void squeezeTextToLabel();
207
208private:
209 std::unique_ptr<class KSqueezedTextLabelPrivate> const d;
210};
211
212#endif // KSQUEEZEDTEXTLABEL_H
A replacement for QLabel that squeezes its text into the label.
void setAlignment(Qt::Alignment)
void clear()
virtual void contextMenuEvent(QContextMenuEvent *ev) override
void setIndent(int)
void setMargin(int)
virtual QSize minimumSizeHint() const const override
virtual void mouseReleaseEvent(QMouseEvent *ev) override
virtual QSize sizeHint() const const override
void setText(const QString &)
Q_PROPERTY(...)
Q_SLOTSQ_SLOTS
typedef Alignment
TextElideMode
QRect contentsRect() const const
virtual void resizeEvent(QResizeEvent *event)
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Tue Mar 26 2024 11:14:43 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.