kalarm/functions.h

   1 /*
   2  *  functions.h  -  miscellaneous functions
   3  *  Program:  kalarm
   4  *  Copyright © 2004-2014 by David Jarvie <djarvie@kde.org>
   5  *
   6  *  This program is free software; you can redistribute it and/or modify
   7  *  it under the terms of the GNU General Public License as published by
   8  *  the Free Software Foundation; either version 2 of the License, or
   9  *  (at your option) any later version.
  10  *
  11  *  This program is distributed in the hope that it will be useful,
  12  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  14  *  GNU General Public License for more details.
  15  *
  16  *  You should have received a copy of the GNU General Public License along
  17  *  with this program; if not, write to the Free Software Foundation, Inc.,
  18  *  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  19  */
  20
  21 #ifndef FUNCTIONS_H
  22 #define FUNCTIONS_H
  23
  24 /**  @file functions.h - miscellaneous functions */
  25
  26 #include "editdlg.h"
  27 #include "eventid.h"
  28
  29 #include <kalarmcal/kaevent.h>
  30 #include <AkonadiCore/collection.h>
  31 #include <AkonadiCore/item.h>
  32 #include <kfile.h>
  33
  34 #include <QSize>
  35 #include <QString>
  36 #include <QVector>
  37 #include <QMimeType>
  38 #include <QUrl>
  39
  40 using namespace KAlarmCal;
  41
  42 namespace KCal { class Event; }
  43 class QWidget;
  44 class QAction;
  45 class QAction;
  46 class KToggleAction;
  47 class MainWindow;
  48 class AlarmListModel;
  49
  50 namespace KAlarm
  51 {
  52
  53 /** Return codes from fileType() */
  54 enum FileType { Unknown, TextPlain, TextFormatted, TextApplication, Image };
  55 /** Return codes from calendar update functions.
  56  *  The codes are ordered by severity, so...
  57  *  DO NOT CHANGE THE ORDER OF THESE VALUES!
  58  */
  59 enum UpdateStatus {
  60     UPDATE_OK,            // update succeeded
  61     UPDATE_KORG_FUNCERR,  // update succeeded, but KOrganizer reported an error updating
  62     UPDATE_KORG_ERRSTART, // update succeeded, but KOrganizer update failed (KOrganizer not fully started)
  63     UPDATE_KORG_ERRINIT,  // update succeeded, but KOrganizer update failed (KOrganizer not started)
  64     UPDATE_KORG_ERR,      // update succeeded, but KOrganizer update failed
  65     UPDATE_ERROR,         // update failed partially
  66     UPDATE_FAILED,        // update failed completely
  67     SAVE_FAILED           // calendar was updated in memory, but save failed
  68 };
  69 /** Error codes supplied as parameter to displayUpdateError() */
  70 enum UpdateError { ERR_ADD, ERR_MODIFY, ERR_DELETE, ERR_REACTIVATE, ERR_TEMPLATE };
  71
  72 /** Result of calendar update. */
  73 struct UpdateResult
  74 {
  75     UpdateStatus  status;   // status code
  76     QString       message;  // error message if any
  77     UpdateResult() : status(UPDATE_OK) {}
  78     explicit UpdateResult(UpdateStatus s, const QString& m = QString()) : status(s), message(m) {}
  79     UpdateResult& operator=(UpdateStatus s)  { status = s; message.clear(); return *this; }
  80     bool operator==(UpdateStatus s) const  { return status == s; }
  81     bool operator!=(UpdateStatus s) const  { return status != s; }
  82     void set(UpdateStatus s) { operator=(s); }
  83     void set(UpdateStatus s, const QString& m) { status = s; message = m; }
  84 };
  85
  86 /** Display a main window with the specified event selected */
  87 MainWindow*         displayMainWindowSelected(Akonadi::Item::Id = -1);
  88 bool                readConfigWindowSize(const char* window, QSize&, int* splitterWidth = Q_NULLPTR);
  89 void                writeConfigWindowSize(const char* window, const QSize&, int splitterWidth = -1);
  90 /** Check from its mime type whether a file appears to be a text or image file.
  91  *  If a text file, its type is distinguished.
  92  */
  93 FileType            fileType(const QMimeType& mimetype);
  94 /** Check that a file exists and is a plain readable file, optionally a text/image file.
  95  *  Display a Continue/Cancel error message if 'errmsgParent' non-null.
  96  */
  97 enum FileErr {
  98     FileErr_None = 0,
  99     FileErr_Blank,           // generic blank error
 100     FileErr_Nonexistent, FileErr_Directory, FileErr_Unreadable, FileErr_NotTextImage,
 101     FileErr_BlankDisplay,    // blank error to use for file to display
 102     FileErr_BlankPlay        // blank error to use for file to play
 103 };
 104 FileErr             checkFileExists(QString& filename, QUrl&);
 105 bool                showFileErrMessage(const QString& filename, FileErr, FileErr blankError, QWidget* errmsgParent);
 106
 107 /** If a url string is a local file, strip off the 'file:/' prefix. */
 108 QString             pathOrUrl(const QString& url);
 109
 110 QString             browseFile(const QString& caption, QString& defaultDir, const QString& initialFile = QString(),
 111                                const QString& filter = QString(), KFile::Modes mode = 0, QWidget* parent = Q_NULLPTR);
 112 bool                editNewAlarm(const QString& templateName, QWidget* parent = Q_NULLPTR);
 113 void                editNewAlarm(EditAlarmDlg::Type, QWidget* parent = Q_NULLPTR);
 114 void                editNewAlarm(KAEvent::SubAction, QWidget* parent = Q_NULLPTR, const AlarmText* = Q_NULLPTR);
 115 void                editNewAlarm(const KAEvent* preset, QWidget* parent = Q_NULLPTR);
 116 void                editAlarm(KAEvent*, QWidget* parent = Q_NULLPTR);
 117 bool                editAlarmById(const EventId& eventID, QWidget* parent = Q_NULLPTR);
 118 void                updateEditedAlarm(EditAlarmDlg*, KAEvent&, Akonadi::Collection&);
 119 void                viewAlarm(const KAEvent*, QWidget* parent = Q_NULLPTR);
 120 void                editNewTemplate(EditAlarmDlg::Type, QWidget* parent = Q_NULLPTR);
 121 void                editNewTemplate(const KAEvent* preset, QWidget* parent = Q_NULLPTR);
 122 void                editTemplate(KAEvent*, QWidget* parent = Q_NULLPTR);
 123 void                execNewAlarmDlg(EditAlarmDlg*);
 124 /** Create a "New From Template" QAction */
 125 KToggleAction*      createAlarmEnableAction(QObject* parent);
 126 QAction*            createStopPlayAction(QObject* parent);
 127 KToggleAction*      createSpreadWindowsAction(QObject* parent);
 128 /** Returns a list of all alarm templates.
 129  *  If shell commands are disabled, command alarm templates are omitted.
 130  */
 131 KAEvent::List       templateList();
 132 void                outputAlarmWarnings(QWidget* parent, const KAEvent* = Q_NULLPTR);
 133 void                refreshAlarms();
 134 void                refreshAlarmsIfQueued();    // must only be called from KAlarmApp::processQueue()
 135 QString             runKMail(bool minimise);
 136
 137 QStringList         dontShowErrors(const EventId&);
 138 bool                dontShowErrors(const EventId&, const QString& tag);
 139 void                setDontShowErrors(const EventId&, const QStringList& tags = QStringList());
 140 void                setDontShowErrors(const EventId&, const QString& tag);
 141 void                setDontShowErrors(const QString& eventId, const QString& tag);
 142
 143 enum         // 'options' parameter values for addEvent(). May be OR'ed together.
 144 {
 145     USE_EVENT_ID       = 0x01,   // use event ID if it's provided
 146     NO_RESOURCE_PROMPT = 0x02,   // don't prompt for resource
 147     ALLOW_KORG_UPDATE  = 0x04    // allow change to be sent to KOrganizer
 148 };
 149 UpdateResult        addEvent(KAEvent&, Akonadi::Collection* = Q_NULLPTR, QWidget* msgParent = Q_NULLPTR, int options = ALLOW_KORG_UPDATE, bool showKOrgErr = true);
 150 UpdateResult        addEvents(QVector<KAEvent>&, QWidget* msgParent = Q_NULLPTR, bool allowKOrgUpdate = true, bool showKOrgErr = true);
 151 bool                addArchivedEvent(KAEvent&, Akonadi::Collection* = Q_NULLPTR);
 152 UpdateResult        addTemplate(KAEvent&, Akonadi::Collection* = Q_NULLPTR, QWidget* msgParent = Q_NULLPTR);
 153 UpdateResult        modifyEvent(KAEvent& oldEvent, KAEvent& newEvent, QWidget* msgParent = Q_NULLPTR, bool showKOrgErr = true);
 154 UpdateResult        updateEvent(KAEvent&, QWidget* msgParent = Q_NULLPTR, bool archiveOnDelete = true);
 155 UpdateResult        updateTemplate(KAEvent&, QWidget* msgParent = Q_NULLPTR);
 156 UpdateResult        deleteEvent(KAEvent&, bool archive = true, QWidget* msgParent = Q_NULLPTR, bool showKOrgErr = true);
 157 UpdateResult        deleteEvents(QVector<KAEvent>&, bool archive = true, QWidget* msgParent = Q_NULLPTR, bool showKOrgErr = true);
 158 UpdateResult        deleteTemplates(const KAEvent::List& events, QWidget* msgParent = Q_NULLPTR);
 159 inline UpdateResult deleteTemplate(KAEvent& event, QWidget* msgParent = Q_NULLPTR)
 160                         { KAEvent::List e;  e += &event;  return deleteTemplates(e, msgParent); }
 161 void                deleteDisplayEvent(const QString& eventID);
 162 UpdateResult        reactivateEvent(KAEvent&, Akonadi::Collection* = Q_NULLPTR, QWidget* msgParent = Q_NULLPTR, bool showKOrgErr = true);
 163 UpdateResult        reactivateEvents(QVector<KAEvent>&, QVector<EventId>& ineligibleIDs, Akonadi::Collection* = Q_NULLPTR, QWidget* msgParent = Q_NULLPTR, bool showKOrgErr = true);
 164 UpdateResult        enableEvents(QVector<KAEvent>&, bool enable, QWidget* msgParent = Q_NULLPTR);
 165 QVector<KAEvent>    getSortedActiveEvents(QObject* parent, AlarmListModel** model = Q_NULLPTR);
 166 void                purgeArchive(int purgeDays);    // must only be called from KAlarmApp::processQueue()
 167 void                displayKOrgUpdateError(QWidget* parent, UpdateError, UpdateResult korgError, int nAlarms = 0);
 168 QStringList         checkRtcWakeConfig(bool checkEventExists = false);
 169 void                deleteRtcWakeConfig();
 170 void                cancelRtcWake(QWidget* msgParent, const QString& eventId = QString());
 171 bool                setRtcWakeTime(unsigned triggerTime, QWidget* parent);
 172
 173 /** Return a prompt string to ask the user whether to convert the calendar to the
 174  *  current format.
 175  *  @param whole if true, the whole calendar needs to be converted; else only some
 176  *               alarms may need to be converted.
 177  */
 178 QString             conversionPrompt(const QString& calendarName, const QString& calendarVersion, bool whole);
 179
 180 Akonadi::Collection invalidCollection();  // for use as a non-const default parameter
 181
 182 #ifndef NDEBUG
 183 void                setTestModeConditions();
 184 void                setSimulatedSystemTime(const KDateTime&);
 185 #endif
 186
 187 } // namespace KAlarm
 188
 189 bool caseInsensitiveLessThan(const QString& s1, const QString& s2);
 190
 191 #endif // FUNCTIONS_H
 192
 193 // vim: et sw=4: