KChart

KChartLegend.h
1 /*
2  * SPDX-FileCopyrightText: 2001-2015 Klaralvdalens Datakonsult AB. All rights reserved.
3  *
4  * This file is part of the KD Chart library.
5  *
6  * SPDX-License-Identifier: GPL-2.0-or-later
7  */
8 
9 #ifndef KCHARTLEGEND_H
10 #define KCHARTLEGEND_H
11 
12 #include "KChartAbstractAreaWidget.h"
13 #include "KChartPosition.h"
14 #include "KChartMarkerAttributes.h"
15 
16 class QTextTable;
17 
18 namespace KChart {
19 
20 class AbstractDiagram;
21 typedef QList<AbstractDiagram*> DiagramList;
22 typedef QList<const AbstractDiagram*> ConstDiagramList;
23 
24 /**
25  * @brief Legend defines the interface for the legend drawing class.
26  *
27  * Legend is the class for drawing legends for all kinds of diagrams ("chart types").
28  *
29  * Legend is drawn on chart level, not per diagram, but you can have more than one
30  * legend per chart, using KChart::Chart::addLegend().
31  *
32  * \note Legend is different from all other classes of KChart, since it can be
33  * displayed outside of the Chart's area. If you want to, you can embed the legend
34  * into your own widget, or into another part of a bigger layout, into which you might
35  * have inserted the Chart.
36  *
37  * On the other hand, please note that you MUST call Chart::addLegend to get your
38  * legend positioned into the correct place of your chart - if you want to have
39  * the legend shown inside of the chart (that's probably true for most cases).
40  */
41 class KCHART_EXPORT Legend : public AbstractAreaWidget
42 {
43  Q_OBJECT
44 
45  Q_DISABLE_COPY( Legend )
46  KCHART_DECLARE_PRIVATE_DERIVED_QWIDGET( Legend )
47 
48 public:
49  explicit Legend( QWidget* parent = nullptr );
50  explicit Legend( KChart::AbstractDiagram* diagram, QWidget* parent = nullptr );
51  ~Legend() override;
52 
53 
54  enum LegendStyle { MarkersOnly = 0,
55  LinesOnly = 1,
56  MarkersAndLines = 2 };
57 
58 
59  void setLegendStyle( LegendStyle style );
60  LegendStyle legendStyle() const;
61 
62 
63 
64  /**
65  * Creates an exact copy of this legend.
66  */
67  virtual Legend * clone() const;
68 
69  /**
70  * Returns true if both legends have the same settings.
71  */
72  bool compare( const Legend* other ) const;
73 
74  void resizeEvent( QResizeEvent * event ) override; // TODO: should be protected
75 
76  virtual void paint( QPainter* painter ) override;
77  void paint( QPainter* painter, const QRect &rect);
78  void setVisible( bool visible ) override;
79 
80  /**
81  Specifies the reference area for font size of title text,
82  and for font size of the item texts, IF automatic area
83  detection is set.
84 
85  \note This parameter is ignored, if the Measure given for
86  setTitleTextAttributes (or setTextAttributes, resp.) is
87  not specifying automatic area detection.
88 
89  If no reference area is specified, but automatic area
90  detection is set, then the size of the legend's parent
91  widget will be used.
92 
93  \sa KChart::Measure, KChartEnums::MeasureCalculationMode
94  */
95  void setReferenceArea( const QWidget* area );
96  /**
97  Returns the reference area, that is used for font size of title text,
98  and for font size of the item texts, IF automatic area
99  detection is set.
100 
101  \sa setReferenceArea
102  */
103  const QWidget* referenceArea() const;
104 
105  /**
106  * The first diagram of the legend or 0 if there was none added to the legend.
107  * @return The first diagram of the legend or 0.
108  *
109  * \sa diagrams, addDiagram, removeDiagram, removeDiagrams, replaceDiagram, setDiagram
110  */
111  KChart::AbstractDiagram* diagram() const;
112 
113  /**
114  * The list of all diagrams associated with the legend.
115  * @return The list of all diagrams associated with the legend.
116  *
117  * \sa diagram, addDiagram, removeDiagram, removeDiagrams, replaceDiagram, setDiagram
118  */
119  DiagramList diagrams() const;
120 
121  /**
122  * @return The list of diagrams associated with this legend.
123  */
124  ConstDiagramList constDiagrams() const;
125 
126  /**
127  * Add the given diagram to the legend.
128  * @param newDiagram The diagram to add.
129  *
130  * \sa diagram, diagrams, removeDiagram, removeDiagrams, replaceDiagram, setDiagram
131  */
132  void addDiagram( KChart::AbstractDiagram* newDiagram );
133 
134  /**
135  * Removes the diagram from the legend's list of diagrams.
136  *
137  * \sa diagram, diagrams, addDiagram, removeDiagrams, replaceDiagram, setDiagram
138  */
139  void removeDiagram( KChart::AbstractDiagram* oldDiagram );
140 
141  /**
142  * Removes all diagrams from the legend's list of diagrams.
143  *
144  * \sa diagram, diagrams, addDiagram, removeDiagram, replaceDiagram, setDiagram
145  */
146  void removeDiagrams();
147 
148  /**
149  * Replaces the old diagram, or appends the
150  * new diagram, it there is none yet.
151  *
152  * @param newDiagram The diagram to be used instead of the old one.
153  * If this parameter is zero, the first diagram will just be removed.
154  *
155  * @param oldDiagram The diagram to be removed by the new one. This
156  * diagram will be deleted automatically. If the parameter is omitted,
157  * the very first diagram will be replaced. In case, there was no
158  * diagram yet, the new diagram will just be added.
159  *
160  * \sa diagram, diagrams, addDiagram, removeDiagram, removeDiagrams, setDiagram
161  */
162  void replaceDiagram( KChart::AbstractDiagram* newDiagram,
163  KChart::AbstractDiagram* oldDiagram = nullptr );
164 
165  /**
166  * Returns the offset of the first dataset of \c diagram.
167  *
168  */
169  uint dataSetOffset( KChart::AbstractDiagram* diagram );
170 
171  /**
172  * @brief A convenience method doing the same as replaceDiagram( newDiagram, 0 );
173  *
174  * Replaces the first diagram by the given diagram.
175  * If the legend's list of diagram is empty the given diagram is added to the list.
176  *
177  * \sa diagram, diagrams, addDiagram, removeDiagram, removeDiagrams, replaceDiagram
178  */
179  void setDiagram( KChart::AbstractDiagram* newDiagram );
180 
181  /**
182  * \brief Specify the position of a non-floating legend.
183  *
184  * Use setFloatingPosition to set position and alignment
185  * if your legend is floating.
186  *
187  * \sa setAlignment, setFloatingPosition
188  */
189  void setPosition( Position position );
190 
191  /**
192  * Returns the position of a non-floating legend.
193  * \sa setPosition
194  */
195  Position position() const;
196 
197  /**
198  * \brief Specify the alignment of a non-floating legend.
199  *
200  * Use setFloatingPosition to set position and alignment
201  * if your legend is floating.
202  *
203  * \sa alignment, setPosition, setFloatingPosition
204  */
205  void setAlignment( Qt::Alignment );
206 
207  /**
208  * Returns the alignment of a non-floating legend.
209  * \sa setAlignment
210  */
211  Qt::Alignment alignment() const;
212 
213  /**
214  * \brief Specify the alignment of the text elements within the legend
215  *
216  * \sa textAlignment()
217  */
218  void setTextAlignment( Qt::Alignment );
219 
220  /**
221  * \brief Returns the alignment used while rendering text elements within the legend.
222  *
223  * \sa setTextAlignment()
224  */
225  Qt::Alignment textAlignment() const;
226 
227  /**
228  * \brief Specify the alignment of the legend symbol( alignment of Legend::LinesOnly)
229  * within the legend
230  *
231  * \sa legendSymbolAlignment()
232  */
233  void setLegendSymbolAlignment(Qt::Alignment);
234 
235  /**
236  * \brief Returns the alignment used while drawing legend symbol(alignment of Legend::LinesOnly)
237  * within the legend.
238  *
239  * \sa setLegendSymbolAlignment()
240  */
241  Qt::Alignment legendSymbolAlignment() const;
242 
243  /**
244  * \brief Specify the position and alignment of a floating legend.
245  *
246  * Use setPosition and setAlignment to set position and alignment
247  * if your legend is non-floating.
248  *
249  * \note When setFloatingPosition is called, the Legend's position value is set to
250  * KChart::Position::Floating automatically.
251  *
252  * If your Chart is pointed to by m_chart, your could have the floating legend
253  * aligned exactly to the chart's coordinate plane's top-right corner
254  * with the following commands:
255 \verbatim
256 KChart::RelativePosition relativePosition;
257 relativePosition.setReferenceArea( m_chart->coordinatePlane() );
258 relativePosition.setReferencePosition( Position::NorthEast );
259 relativePosition.setAlignment( Qt::AlignTop | Qt::AlignRight );
260 relativePosition.setHorizontalPadding(
261  KChart::Measure( -1.0, KChartEnums::MeasureCalculationModeAbsolute ) );
262 relativePosition.setVerticalPadding(
263  KChart::Measure( 0.0, KChartEnums::MeasureCalculationModeAbsolute ) );
264 m_legend->setFloatingPosition( relativePosition );
265 \endverbatim
266  *
267  * To have the legend positioned at a fixed point, measured from the QPainter's top left corner,
268  * you could use the following code code:
269  *
270 \verbatim
271 KChart::RelativePosition relativePosition;
272 relativePosition.setReferencePoints( PositionPoints( QPointF( 0.0, 0.0 ) ) );
273 relativePosition.setReferencePosition( Position::NorthWest );
274 relativePosition.setAlignment( Qt::AlignTop | Qt::AlignLeft );
275 relativePosition.setHorizontalPadding(
276  KChart::Measure( 4.0, KChartEnums::MeasureCalculationModeAbsolute ) );
277 relativePosition.setVerticalPadding(
278  KChart::Measure( 4.0, KChartEnums::MeasureCalculationModeAbsolute ) );
279 m_legend->setFloatingPosition( relativePosition );
280 \endverbatim
281  * Actually that's exactly the code KChart is using as default position for any floating legends,
282  * so if you just say setPosition( KChart::Position::Floating ) without calling setFloatingPosition
283  * your legend will be positioned at point 4/4.
284  *
285  * \sa setPosition, setAlignment
286  */
287  void setFloatingPosition( const RelativePosition& relativePosition );
288 
289  /**
290  * Returns the position of a floating legend.
291  * \sa setFloatingPosition
292  */
293  const RelativePosition floatingPosition() const;
294 
295  void setOrientation( Qt::Orientation orientation );
296  Qt::Orientation orientation() const;
297 
298 
299  void setSortOrder( Qt::SortOrder order );
300  Qt::SortOrder sortOrder() const;
301 
302  void setShowLines( bool legendShowLines );
303  bool showLines() const;
304 
305 
306  /**
307  \brief Removes all legend texts that might have been set by setText.
308 
309  This resets the Legend to default behaviour: Texts are created automatically.
310  */
311  void resetTexts();
312  void setText( uint dataset, const QString& text );
313  QString text( uint dataset ) const;
314  const QMap<uint,QString> texts() const;
315 
316  /**
317  * Sets a list of datasets that are to be hidden in the legend.
318  *
319  * By passing an empty list, you show all datasets.
320  * All datasets are shown by default, which means
321  * that hiddenDatasets() returns an empty list.
322  */
323  void setHiddenDatasets( const QList<uint> hiddenDatasets );
324  const QList<uint> hiddenDatasets() const;
325  void setDatasetHidden( uint dataset, bool hidden );
326  bool datasetIsHidden( uint dataset ) const;
327 
328  uint datasetCount() const;
329 
330  void setDefaultColors();
331  void setRainbowColors();
332  void setSubduedColors( bool ordered = false );
333 
334  void setBrushesFromDiagram( KChart::AbstractDiagram* diagram );
335 
336  /**
337  * Note: there is no color() getter method, since setColor
338  * just sets a QBrush with the respective color, so the
339  * brush() getter method is sufficient.
340  */
341  void setColor( uint dataset, const QColor& color );
342 
343  void setBrush( uint dataset, const QBrush& brush );
344  QBrush brush( uint dataset ) const;
345  const QMap<uint,QBrush> brushes() const;
346 
347  void setPen( uint dataset, const QPen& pen );
348  QPen pen( uint dataset ) const;
349  const QMap<uint,QPen> pens() const;
350 
351  /**
352  * Note that any sizes specified via setMarkerAttributes are ignored,
353  * unless you disable the automatic size calculation, by saying
354  * setUseAutomaticMarkerSize( false )
355  */
356  void setMarkerAttributes( uint dataset, const MarkerAttributes& );
357  MarkerAttributes markerAttributes( uint dataset ) const;
358  const QMap<uint, MarkerAttributes> markerAttributes() const;
359 
360  /**
361  * This option is on by default, it means that Marker sizes in the Legend
362  * will be the same as the font height used for their respective label texts.
363  *
364  * Set this to false, if you want to specify the marker sizes via setMarkerAttributes
365  * or if you want the Legend to use the same marker sizes as they are used in the Diagrams.
366  */
367  void setUseAutomaticMarkerSize( bool useAutomaticMarkerSize );
368  bool useAutomaticMarkerSize() const;
369 
370  void setTextAttributes( const TextAttributes &a );
371  TextAttributes textAttributes() const;
372 
373  void setTitleText( const QString& text );
374  QString titleText() const;
375 
376  void setTitleTextAttributes( const TextAttributes &a );
377  TextAttributes titleTextAttributes() const;
378 
379  void setSpacing( uint space );
380  uint spacing() const;
381 
382  // called internally by KChart::Chart, when painting into a custom QPainter
383  void forceRebuild() override;
384 
385  QSize minimumSizeHint() const override;
386  QSize sizeHint() const override;
387  bool hasHeightForWidth() const override;
388  int heightForWidth( int width ) const override;
389  void needSizeHint() override;
390  void resizeLayout( const QSize& size ) override;
391 
392 Q_SIGNALS:
393  void destroyedLegend( KChart::Legend* );
394  /** Emitted upon change of a property of the Legend or any of its components. */
395  void propertiesChanged();
396 
397 private Q_SLOTS:
398  void emitPositionChanged();
399  void resetDiagram( KChart::AbstractDiagram* );
400  void activateTheLayout();
401  void setNeedRebuild();
402  void buildLegend();
403 }; // End of class Legend
404 
405 }
406 
407 
408 #endif // KCHARTLEGEND_H
Defines relative position information: reference area, position in this area (reference position)...
Class only listed here to document inheritance of some KChart classes.
Legend defines the interface for the legend drawing class.
Definition: KChartLegend.h:41
AbstractDiagram defines the interface for diagram classes.
A set of attributes controlling the appearance of data set markers.
Defines a position, using compass terminology.
typedef Alignment
SortOrder
A set of text attributes.
An area in the chart with a background, a frame, etc.
Orientation
Global namespace.
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Sat Jan 22 2022 22:33:27 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.