KGantt

kganttdatetimegrid.h
1 /*
2  * SPDX-FileCopyrightText: 2001-2015 Klaralvdalens Datakonsult AB. All rights reserved.
3  *
4  * This file is part of the KGantt library.
5  *
6  * SPDX-License-Identifier: GPL-2.0-or-later
7  */
8 
9 #ifndef KGANTTDATETIMEGRID_H
10 #define KGANTTDATETIMEGRID_H
11 
12 #include "kganttabstractgrid.h"
13 
14 #include <QDateTime>
15 #include <QSet>
16 #include <QPair>
17 
18 namespace KGantt {
19 
20  class DateTimeScaleFormatter;
21  class DateTimeTimeLine;
22 
23 
24  /*!\class KGantt::DateTimeGrid
25  * \ingroup KGantt
26  *
27  * This implementation of AbstractGrid works with QDateTime
28  * and shows days and week numbers in the header
29  */
30  class KGANTT_EXPORT DateTimeGrid : public AbstractGrid
31  {
32  Q_OBJECT
33  KGANTT_DECLARE_PRIVATE_DERIVED( DateTimeGrid )
34  public:
35  enum Scale {
36  ScaleAuto,
37  ScaleHour,
38  ScaleDay,
39  ScaleWeek,
40  ScaleMonth,
41  ScaleUserDefined
42  };
43  enum HeaderType {
44  NoHeader,
45  UpperHeader,
46  LowerHeader
47  };
48 
49  DateTimeGrid();
50  ~DateTimeGrid() override;
51 
52  /*! \returns The QDateTime used as start date for the grid.
53  *
54  * The default is three days before the current date.
55  */
56  QDateTime startDateTime() const;
57 
58  /*! \param dt The start date of the grid. It is used as the beginning of the
59  * horizontal scrollbar in the view.
60  *
61  * Emits gridChanged() after the start date has changed.
62  */
63  void setStartDateTime( const QDateTime& dt );
64 
65  /*! \returns The width in pixels for each day in the grid.
66  *
67  * The default is 100 pixels.
68  */
69  qreal dayWidth() const;
70 
71  /*! \param w The width in pixels for each day in the grid.
72  *
73  * The signal gridChanged() is emitted after the day width is changed.
74  */
75  void setDayWidth( qreal );
76 
77  /*! Maps a given point in time \a dt to an X value in the scene.
78  */
79  qreal mapFromDateTime( const QDateTime& dt) const;
80 
81  /*! Maps a given X value \a x in scene coordinates to a point in time.
82  */
83  QDateTime mapToDateTime( qreal x ) const;
84 
85  /*! \param ws The start day of the week.
86  *
87  * A solid line is drawn on the grid to mark the beginning of a new week.
88  * Emits gridChanged() after the start day has changed.
89  */
90  void setWeekStart( Qt::DayOfWeek );
91 
92  /*! \returns The start day of the week */
93  Qt::DayOfWeek weekStart() const;
94 
95  /*! \param fd A set of days to mark as free in the grid.
96  *
97  * Free days are filled with the alternate base brush of the
98  * palette used by the view.
99  * The signal gridChanged() is emitted after the free days are changed.
100  */
101  void setFreeDays( const QSet<Qt::DayOfWeek>& fd );
102 
103  /*! \returns The days marked as free in the grid. */
104  QSet<Qt::DayOfWeek> freeDays() const;
105 
106  /*! Sets the brush to use to paint free days.
107  */
108  void setFreeDaysBrush(const QBrush brush);
109 
110  /*!
111  \returns The brush used to paint free days.
112  */
113  QBrush freeDaysBrush() const;
114 
115  /*! \param s The scale to be used to paint the grid.
116  *
117  * The signal gridChanged() is emitted after the scale has changed.
118  * \sa Scale
119  *
120  * Following example demonstrates how to change the format of the header to use
121  * a date-scaling with the header-label displayed with the ISO date-notation.
122  * \code
123  * DateTimeScaleFormatter* formatter = new DateTimeScaleFormatter(DateTimeScaleFormatter::Day, QString::fromLatin1("yyyy-MMMM-dddd"));
124  * grid->setUserDefinedUpperScale( formatter );
125  * grid->setUserDefinedLowerScale( formatter );
126  * grid->setScale( DateTimeGrid::ScaleUserDefined );
127  * \endcode
128  */
129  void setScale( Scale s );
130 
131  /*! \returns The scale used to paint the grid.
132  *
133  * The default is ScaleAuto, which means the day scale will be used
134  * as long as the day width is less or equal to 500.
135  * \sa Scale
136  */
137  Scale scale() const;
138 
139  /*! Sets the scale formatter for the lower part of the header to the
140  * user defined formatter to \a lower. The DateTimeGrid object takes
141  * ownership of the formatter, which has to be allocated with new.
142  *
143  * You have to set the scale to ScaleUserDefined for this setting to take effect.
144  * \sa DateTimeScaleFormatter
145  */
146  void setUserDefinedLowerScale( DateTimeScaleFormatter* lower );
147 
148  /*! Sets the scale formatter for the upper part of the header to the
149  * user defined formatter to \a upper. The DateTimeGrid object takes
150  * ownership of the formatter, which has to be allocated with new.
151  *
152  * You have to set the scale to ScaleUserDefined for this setting to take effect.
153  * \sa DateTimeScaleFormatter
154  */
155  void setUserDefinedUpperScale( DateTimeScaleFormatter* upper );
156 
157  /*! \return The DateTimeScaleFormatter being used to render the lower scale.
158  */
159  DateTimeScaleFormatter* userDefinedLowerScale() const;
160 
161 
162  /*! \return The DateTimeScaleFormatter being used to render the upper scale.
163  */
164  DateTimeScaleFormatter* userDefinedUpperScale() const;
165 
166  /*! \returns true if row separators are used. */
167  bool rowSeparators() const;
168 
169  /*! \param enable Whether to use row separators or not. */
170  void setRowSeparators( bool enable );
171 
172  /*! Sets the brush used to display rows where no data is found.
173  * Default is a red pattern. If set to QBrush() rows with no
174  * information will not be marked.
175  */
176  void setNoInformationBrush( const QBrush& brush );
177 
178  /*! \returns the brush used to mark rows with no information.
179  */
180  QBrush noInformationBrush() const;
181 
182  /*! \param idx The index to get the Span for.
183  * \returns The start and end pixels, in a Span, of the specified index.
184  */
185  /*reimp*/ Span mapToChart( const QModelIndex& idx ) const override;
186 
187  /*! Maps the supplied Span to QDateTimes, and puts them as start time and
188  * end time for the supplied index.
189  *
190  * \param span The span used to map from.
191  * \param idx The index used for setting the start time and end time in the model.
192  * \param constraints A list of hard constraints to match against the start time and
193  * end time mapped from the span.
194  *
195  * \returns true if the start time and time was successfully added to the model, or false
196  * if unsuccessful.
197  * Also returns false if any of the constraints isn't satisfied. That is, if the start time of
198  * the constrained index is before the end time of the dependency index, or the end time of the
199  * constrained index is before the start time of the dependency index.
200  */
201  /*reimp*/ bool mapFromChart( const Span& span, const QModelIndex& idx,
202  const QList<Constraint>& constraints=QList<Constraint>() ) const override;
203 
204  /*!
205  * \param value The datetime to get the x value for.
206  * \returns The x value corresponding to \a value or -1.0 if \a value is not a datetime variant.
207  */
208  /*reimp*/ qreal mapToChart( const QVariant& value ) const override;
209 
210  /*!
211  * \param x The x value to get the datetime for.
212  * \returns The datetime corresponding to \a x or an invalid datetime if x cannot be mapped.
213  */
214  /*reimp*/ QVariant mapFromChart( qreal x ) const override;
215  /*reimp*/ void paintGrid( QPainter* painter,
216  const QRectF& sceneRect, const QRectF& exposedRect,
217  AbstractRowController* rowController = nullptr,
218  QWidget* widget = nullptr ) override;
219  /*reimp*/ void paintHeader( QPainter* painter,
220  const QRectF& headerRect, const QRectF& exposedRect,
221  qreal offset, QWidget* widget = nullptr ) override;
222 
223  /**
224  * @return the timeline control object
225  */
226  DateTimeTimeLine *timeLine() const;
227 
228  HeaderType sectionHandleAtPos(int x, int y, const QRect &headerRect) const;
229 
230  protected:
231  /*! Paints the hour scale header.
232  * \sa paintHeader()
233  */
234  virtual void paintHourScaleHeader( QPainter* painter,
235  const QRectF& headerRect, const QRectF& exposedRect,
236  qreal offset, QWidget* widget = nullptr );
237 
238  /*! Paints the day scale header.
239  * \sa paintHeader()
240  */
241  virtual void paintDayScaleHeader( QPainter* painter,
242  const QRectF& headerRect, const QRectF& exposedRect,
243  qreal offset, QWidget* widget = nullptr );
244 
245  /*! Paints the week scale header.
246  * \sa paintHeader()
247  */
248  virtual void paintWeekScaleHeader( QPainter* painter,
249  const QRectF& headerRect, const QRectF& exposedRect,
250  qreal offset, QWidget* widget = nullptr );
251 
252  /*! Paints the week scale header.
253  * \sa paintHeader()
254  */
255  virtual void paintMonthScaleHeader( QPainter* painter,
256  const QRectF& headerRect, const QRectF& exposedRect,
257  qreal offset, QWidget* widget = nullptr );
258 
259  virtual void paintUserDefinedHeader( QPainter* painter,
260  const QRectF& headerRect, const QRectF& exposedRect,
261  qreal offset, const DateTimeScaleFormatter* formatter,
262  QWidget* widget = nullptr );
263 
264 
265  /*! Draw the background for a day.
266  */
267  virtual void drawDayBackground(QPainter* painter, const QRectF& rect, const QDate& date);
268 
269  /*! Draw the foreground for a day.
270  */
271  virtual void drawDayForeground(QPainter* painter, const QRectF& rect, const QDate& date);
272 
273  /** Return the rectangle that represents the date-range.
274  */
275  QRectF computeRect(const QDateTime& from, const QDateTime& to, const QRectF& rect) const;
276 
277 
278  /** Return a date-range represented by the rectangle.
279  */
280  QPair<QDateTime, QDateTime> dateTimeRange(const QRectF& rect) const;
281 
282  /* reimp */ void drawBackground(QPainter* paint, const QRectF& rect) override;
283  /* reimp */ void drawForeground(QPainter* paint, const QRectF& rect) override;
284  };
285 
286  /*!\class KGantt::DateTimeScaleFormatter
287  * \ingroup KGantt
288  *
289  * This class formats dates and times used in DateTimeGrid follawing a given format.
290  *
291  * The format follows the format of QDateTime::toString(), with one addition:
292  * "w" is replaced with the week number of the date as number without a leading zero (1-53)
293  * "ww" is replaced with the week number of the date as number with a leading zero (01-53)
294  *
295  * For example:
296  *
297  * \code
298  * // formatter to print the complete date over the current week
299  * // This leads to the first day of the week being printed
300  * DateTimeScaleFormatter formatter = DateTimeScaleFormatter( DateTimeScaleFormatter::Week, "yyyy-MM-dd" );
301  * \endcode
302  *
303  * Optionally, you can set an user defined text alignment flag. The default value is Qt::AlignCenter.
304  * \sa DateTimeScaleFormatter::DateTimeScaleFormatter
305  *
306  * This class even controls the range of the grid sections.
307  * \sa KGanttDateTimeScaleFormatter::Range
308  */
309  class KGANTT_EXPORT DateTimeScaleFormatter
310  {
311  KGANTT_DECLARE_PRIVATE_BASE_POLYMORPHIC( DateTimeScaleFormatter )
312  public:
313  enum Range {
314  Second,
315  Minute,
316  Hour,
317  Day,
318  Week,
319  Month,
320  Year
321  };
322 
323  /*! Creates a DateTimeScaleFormatter using \a range and \a format.
324  * The text on the header is aligned following \a alignment.
325  */
326  DateTimeScaleFormatter( Range range, const QString& formatString,
327  Qt::Alignment alignment = Qt::AlignCenter );
328  DateTimeScaleFormatter( Range range, const QString& formatString,
329  const QString& templ, Qt::Alignment alignment = Qt::AlignCenter );
330 
331  /*! \returns The format being used for formatting dates and times.
332  */
334  virtual ~DateTimeScaleFormatter();
335 
336  DateTimeScaleFormatter& operator=( const DateTimeScaleFormatter& other );
337 
338  /*! \returns The format string
339  */
340  QString format() const;
341 
342  /*! \returns The range of each item on a DateTimeGrid header.
343  * \sa DateTimeScaleFormatter::Range */
344  Range range() const;
345  Qt::Alignment alignment() const;
346 
347  /*! \returns the QDateTime being the begin of the range after the one containing \a datetime
348  * \sa currentRangeBegin
349  */
350  virtual QDateTime nextRangeBegin( const QDateTime& datetime ) const;
351 
352  /*! \returns the QDateTime being the begin of the range containing \a datetime
353  * \sa nextRangeBegin
354  */
355  virtual QDateTime currentRangeBegin( const QDateTime& datetime ) const;
356 
357  /*! \returns The \a datetime as string respecting the format.
358  */
359  QString format( const QDateTime& datetime ) const;
360  virtual QString text( const QDateTime& datetime ) const;
361  };
362 }
363 
364 
365 
366 #ifndef QT_NO_DEBUG_STREAM
367 QDebug KGANTT_EXPORT operator<<( QDebug dbg, KGantt::DateTimeScaleFormatter::Range );
368 #endif
369 
370 #endif /* KGANTTDATETIMEGRID_H */
371 
Abstract baseclass for row controllers. A row controller is used by the GraphicsView to nagivate the ...
typedef Alignment
DayOfWeek
Global namespace.
Abstract baseclass for grids. A grid is used to convert between QModelIndex&#39;es and gantt chart values...
QDataStream & operator<<(QDataStream &out, const KDateTime::Spec &spec)
A class representing a start point and a length.
Definition: kganttglobal.h:240
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Sun Dec 5 2021 22:32:42 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.