File indexing completed on 2024-06-16 04:57:11
0001 /* 0002 This file is part of the KOrganizer interfaces. 0003 0004 SPDX-FileCopyrightText: 1999, 2001, 2003 Cornelius Schumacher <schumacher@kde.org> 0005 SPDX-FileCopyrightText: 2004 Reinhold Kainhofer <reinhold@kainhofer.com> 0006 0007 SPDX-License-Identifier: LGPL-2.0-or-later 0008 */ 0009 0010 #pragma once 0011 0012 #include "korganizer_interfaces_export.h" 0013 0014 #include <CalendarSupport/PrintPlugin> 0015 #include <EventViews/EventView> 0016 0017 #include <Akonadi/ETMCalendar> 0018 #include <Akonadi/IncidenceChanger> 0019 0020 #include <Akonadi/Collection> 0021 #include <Akonadi/Item> 0022 0023 #include <QWidget> 0024 0025 #include <memory> 0026 0027 namespace KOrg 0028 { 0029 class BaseViewPrivate; 0030 0031 /** 0032 This class provides an interface for all views being displayed within the 0033 main calendar view. It has functions to update the view, to specify date 0034 range and other display parameter and to return selected objects. An 0035 important class, which inherits KOBaseView is KOEventView, which provides 0036 the interface for all views of event data like the agenda or the month view. 0037 0038 @short Base class for calendar views 0039 @author Preston Brown, Cornelius Schumacher 0040 @see KOTodoView, KOEventView, KOListView, KOAgendaView, KOMonthView 0041 */ 0042 class KORGANIZER_INTERFACES_EXPORT BaseView : public QWidget 0043 { 0044 Q_OBJECT 0045 public: 0046 /** 0047 Constructs a view. 0048 0049 @param cal Pointer to the calendar object from which events 0050 will be retrieved for display. 0051 @param parent parent widget. 0052 */ 0053 explicit BaseView(QWidget *parent = nullptr); 0054 0055 /** 0056 Destructor. Views will do view-specific cleanups here. 0057 */ 0058 ~BaseView() override; 0059 0060 /** 0061 * Sets the model used to display events. 0062 */ 0063 virtual void setModel(QAbstractItemModel *model); 0064 0065 QAbstractItemModel *model() const; 0066 0067 /** 0068 @return a list of selected events. Most views can probably only 0069 select a single event at a time, but some may be able to select 0070 more than one. 0071 */ 0072 virtual Akonadi::Item::List selectedIncidences() = 0; 0073 0074 /** 0075 Returns a list of the dates of selected events. Most views can 0076 probably only select a single event at a time, but some may be able 0077 to select more than one. 0078 */ 0079 virtual KCalendarCore::DateList selectedIncidenceDates() = 0; 0080 0081 /** 0082 Returns the start of the selection, or an invalid QDateTime if there is no selection 0083 or the view doesn't support selecting cells. 0084 */ 0085 virtual QDateTime selectionStart(); 0086 0087 /** 0088 Returns the end of the selection, or an invalid QDateTime if there is no selection 0089 or the view doesn't support selecting cells. 0090 */ 0091 virtual QDateTime selectionEnd(); 0092 0093 virtual CalendarSupport::CalPrinterBase::PrintType printType() const; 0094 0095 /** 0096 Returns the number of currently shown dates. 0097 A return value of 0 means no idea. 0098 */ 0099 virtual int currentDateCount() const = 0; 0100 0101 /** 0102 Returns if this view is a view for displaying events. 0103 */ 0104 virtual bool isEventView(); 0105 0106 /** 0107 * Returns which incidence types should used to embolden 0108 * day numbers in the date navigator when this view is selected. 0109 * 0110 * BaseView provides a default implementation that only highlights 0111 * events because that's how the behaviour has always been, and 0112 * most views are event orientated, even one or two 0113 * which don't inherit KOEventView are about events (timespent). 0114 * 0115 * This function writes to these 3 parameters the result, 0116 * the original value is ignored 0117 */ 0118 virtual void getHighlightMode(bool &highlightEvents, bool &highlightTodos, bool &highlightJournals); 0119 0120 /** 0121 * returns whether this view should be displayed full window. 0122 * Base implementation returns false. 0123 */ 0124 virtual bool usesFullWindow(); 0125 0126 /** 0127 * returns whether this view supports zoom. 0128 * Base implementation returns false. 0129 */ 0130 virtual bool supportsZoom(); 0131 0132 /** 0133 * returns whether this view supports date range selection 0134 * Base implementation returns true. 0135 */ 0136 virtual bool supportsDateRangeSelection(); 0137 0138 virtual bool hasConfigurationDialog() const; 0139 0140 virtual void showConfigurationDialog(QWidget *parent); 0141 0142 QByteArray identifier() const; 0143 virtual void setIdentifier(const QByteArray &identifier); 0144 0145 /** 0146 * reads the view configuration. View-specific configuration can be 0147 * restored via doRestoreConfig() 0148 * 0149 * @param configGroup the group to read settings from 0150 * @see doRestoreConfig() 0151 */ 0152 virtual void restoreConfig(const KConfigGroup &configGroup); 0153 0154 /** 0155 * writes out the view configuration. View-specific configuration can be 0156 * saved via doSaveConfig() 0157 * 0158 * @param configGroup the group to store settings in 0159 * @see doSaveConfig() 0160 */ 0161 virtual void saveConfig(KConfigGroup &configGroup); 0162 0163 /** 0164 * returns the view at the given widget coordinate. This is usually the view 0165 * itself, except for composite views, where a subview will be returned. 0166 * The default implementation returns @p this . 0167 */ 0168 virtual BaseView *viewAt(const QPoint &p); 0169 0170 /** 0171 Show incidences for the given date range. The date range actually shown 0172 may be different from the requested range, depending on the particular 0173 requirements of the view. 0174 0175 @param start Start of date range. 0176 @param end End of date range. 0177 */ 0178 virtual void setDateRange(const QDateTime &start, const QDateTime &end, const QDate &preferredMonth = QDate()); 0179 0180 QDateTime startDateTime() const; 0181 QDateTime endDateTime() const; 0182 0183 QDateTime actualStartDateTime() const; 0184 QDateTime actualEndDateTime() const; 0185 0186 /** Returns true if the view supports navigation through the date navigator 0187 ( selecting a date range, changing month, changing year, etc. ) 0188 */ 0189 virtual bool supportsDateNavigation() const 0190 { 0191 return false; 0192 } 0193 0194 virtual Akonadi::Collection::Id collectionId() const 0195 { 0196 return -1; 0197 } 0198 0199 public Q_SLOTS: 0200 /** 0201 Shows given incidences. Depending on the actual view it might not 0202 be possible to show all given events. 0203 0204 @param incidenceList a list of incidences to show. 0205 @param date is the QDate on which the incidences are being shown. 0206 */ 0207 virtual void showIncidences(const Akonadi::Item::List &incidenceList, const QDate &date) = 0; 0208 0209 /** 0210 Updates the current display to reflect changes that may have happened 0211 in the calendar since the last display refresh. 0212 */ 0213 virtual void updateView() = 0; 0214 virtual void dayPassed(const QDate &); 0215 0216 /** 0217 Assign a new incidence change helper object. 0218 */ 0219 virtual void setIncidenceChanger(Akonadi::IncidenceChanger *changer); 0220 0221 /** 0222 Write all unsaved data back to calendar store. 0223 */ 0224 virtual void flushView(); 0225 0226 /** 0227 Updates the current display to reflect the changes to one particular incidence. 0228 */ 0229 virtual void changeIncidenceDisplay(const Akonadi::Item &, Akonadi::IncidenceChanger::ChangeType) = 0; 0230 0231 /** 0232 Re-reads the KOrganizer configuration and picks up relevant 0233 changes which are applicable to the view. 0234 */ 0235 virtual void updateConfig(); 0236 0237 /** 0238 Clear selection. The incidenceSelected signal is not emitted. 0239 */ 0240 virtual void clearSelection(); 0241 0242 /** 0243 Sets the default start/end date/time for new events. 0244 Return true if anything was changed 0245 */ 0246 virtual bool eventDurationHint(QDateTime &startDt, QDateTime &endDt, bool &allDay); 0247 0248 virtual void calendarAdded(const Akonadi::CollectionCalendar::Ptr &calendar); 0249 virtual void calendarRemoved(const Akonadi::CollectionCalendar::Ptr &calendar); 0250 0251 Q_SIGNALS: 0252 void incidenceSelected(const Akonadi::Item &, const QDate); 0253 0254 /** 0255 * instructs the receiver to show the incidence in read-only mode. 0256 */ 0257 void showIncidenceSignal(const Akonadi::Item &); 0258 0259 /** 0260 * instructs the receiver to begin editing the incidence specified in 0261 * some manner. Doesn't make sense to connect to more than one 0262 * receiver. 0263 */ 0264 void editIncidenceSignal(const Akonadi::Item &); 0265 0266 /** 0267 * instructs the receiver to delete the Incidence in some manner; some 0268 * possibilities include automatically, with a confirmation dialog 0269 * box, etc. Doesn't make sense to connect to more than one receiver. 0270 */ 0271 void deleteIncidenceSignal(const Akonadi::Item &); 0272 0273 /** 0274 * instructs the receiver to cut the Incidence 0275 */ 0276 void cutIncidenceSignal(const Akonadi::Item &); 0277 0278 /** 0279 * instructs the receiver to copy the incidence 0280 */ 0281 void copyIncidenceSignal(const Akonadi::Item &); 0282 0283 /** 0284 * instructs the receiver to paste the incidence 0285 */ 0286 void pasteIncidenceSignal(); 0287 0288 /** 0289 * instructs the receiver to toggle the alarms of the Incidence. 0290 */ 0291 void toggleAlarmSignal(const Akonadi::Item &); 0292 0293 /** 0294 * instructs the receiver to toggle the completion state of the Incidence 0295 * (which must be a Todo type). 0296 */ 0297 void toggleTodoCompletedSignal(const Akonadi::Item &); 0298 0299 /** 0300 * Toggle the completion state of the incidence contained in the item 0301 * (which must be a Todo) on the given date. If the todo recurs, the 0302 * QDate identifies the occurrence to toggle. 0303 */ 0304 void toggleOccurrenceCompletedSignal(const Akonadi::Item &, const QDate &); 0305 0306 /** 0307 * Copy the incidence to the specified resource. 0308 */ 0309 void copyIncidenceToResourceSignal(const Akonadi::Item &, const Akonadi::Collection &); 0310 0311 /** 0312 * Move the incidence to the specified resource. 0313 */ 0314 void moveIncidenceToResourceSignal(const Akonadi::Item &, const Akonadi::Collection &); 0315 0316 /** Dissociate from a recurring incidence the occurrence on the given 0317 * date to a new incidence or dissociate all occurrences from the 0318 * given date onwards. 0319 */ 0320 void dissociateOccurrencesSignal(const Akonadi::Item &, const QDate &); 0321 0322 void startMultiModify(const QString &); 0323 void endMultiModify(); 0324 0325 /** 0326 * instructs the receiver to create a new event in given collection. Doesn't make 0327 * sense to connect to more than one receiver. 0328 */ 0329 void newEventSignal(); 0330 0331 /** 0332 * instructs the receiver to create a new event with the specified beginning 0333 * time. Doesn't make sense to connect to more than one receiver. 0334 */ 0335 void newEventSignal(const QDate &); 0336 0337 /** 0338 * instructs the receiver to create a new event with the specified beginning 0339 * time. Doesn't make sense to connect to more than one receiver. 0340 */ 0341 void newEventSignal(const QDateTime &); 0342 0343 /** 0344 * instructs the receiver to create a new event, with the specified 0345 * beginning end ending times. Doesn't make sense to connect to more 0346 * than one receiver. 0347 */ 0348 void newEventSignal(const QDateTime &, const QDateTime &); 0349 0350 void newTodoSignal(const QDate &); 0351 void newSubTodoSignal(const Akonadi::Item &); 0352 0353 void newJournalSignal(const QDate &); 0354 0355 public: 0356 /** 0357 Notifies the view that there are pending changes so a redraw is needed. 0358 0359 @param changes Types of changes that were made 0360 */ 0361 virtual void setChanges(EventViews::EventView::Changes changes); 0362 0363 /** 0364 Returns if there are pending changes and a redraw is needed. 0365 */ 0366 EventViews::EventView::Changes changes() const; 0367 0368 protected: 0369 /** 0370 * reimplement to read view-specific settings 0371 */ 0372 virtual void doRestoreConfig(const KConfigGroup &configGroup); 0373 0374 /** 0375 * reimplement to write view specific settings 0376 */ 0377 virtual void doSaveConfig(KConfigGroup &configGroup); 0378 0379 /** 0380 @deprecated 0381 */ 0382 virtual void showDates(const QDate &start, const QDate &end, const QDate &preferredMonth = QDate()) = 0; 0383 0384 /** 0385 * From the requested date range (passed via setDateRange()), calculates the 0386 * adjusted date range actually displayed by the view, depending on the view's 0387 * supported range (e.g., a month view always displays one month). 0388 * The default implementation returns the range unmodified 0389 */ 0390 virtual QPair<QDateTime, QDateTime> actualDateRange(const QDateTime &start, const QDateTime &end, const QDate &preferredMonth = QDate()) const; 0391 0392 Akonadi::CollectionCalendar::Ptr calendarForCollection(Akonadi::Collection::Id collectionId) const; 0393 Akonadi::CollectionCalendar::Ptr calendarForIncidence(const KCalendarCore::Incidence::Ptr &incidence) const; 0394 0395 protected Q_SLOTS: 0396 virtual void calendarReset(); 0397 0398 protected: 0399 Akonadi::IncidenceChanger *mChanger = nullptr; 0400 0401 private: 0402 std::unique_ptr<BaseViewPrivate> const d; 0403 friend class KOrg::BaseViewPrivate; 0404 }; 0405 }