kalarm/functions.h

   1 /*
   2  *  functions.h  -  miscellaneous functions
   3  *  Program:  kalarm
   4  *  Copyright © 2004-2012 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 #ifdef USE_AKONADI
  28 #include "eventid.h"
  29 #endif
  30
  31 #include <kalarmcal/kaevent.h>
  32 #ifdef USE_AKONADI
  33 #include <akonadi/collection.h>
  34 #include <akonadi/item.h>
  35 #endif
  36 #include <kfile.h>
  37 #include <kmimetype.h>
  38
  39 #include <QSize>
  40 #include <QString>
  41 #include <QVector>
  42
  43 using namespace KAlarmCal;
  44
  45 namespace KCal { class Event; }
  46 class QWidget;
  47 class QAction;
  48 class KAction;
  49 class KActionCollection;
  50 class KToggleAction;
  51 class AlarmResource;
  52 class MainWindow;
  53 class TemplateMenuAction;
  54 #ifdef USE_AKONADI
  55 class AlarmListModel;
  56 #endif
  57
  58 namespace KAlarm
  59 {
  60
  61 /** Return codes from fileType() */
  62 enum FileType { Unknown, TextPlain, TextFormatted, TextApplication, Image };
  63 /** Return codes from calendar update functions.
  64  *  The codes are ordered by severity, so...
  65  *  DO NOT CHANGE THE ORDER OF THESE VALUES!
  66  */
  67 enum UpdateStatus {
  68     UPDATE_OK,            // update succeeded
  69     UPDATE_KORG_FUNCERR,  // update succeeded, but KOrganizer reported an error updating
  70     UPDATE_KORG_ERRSTART, // update succeeded, but KOrganizer update failed (KOrganizer not fully started)
  71     UPDATE_KORG_ERR,      // update succeeded, but KOrganizer update failed
  72     UPDATE_ERROR,         // update failed partially
  73     UPDATE_FAILED,        // update failed completely
  74     SAVE_FAILED           // calendar was updated in memory, but save failed
  75 };
  76 /** Error codes supplied as parameter to displayUpdateError() */
  77 enum UpdateError { ERR_ADD, ERR_MODIFY, ERR_DELETE, ERR_REACTIVATE, ERR_TEMPLATE };
  78
  79
  80 /** Display a main window with the specified event selected */
  81 #ifdef USE_AKONADI
  82 MainWindow*         displayMainWindowSelected(Akonadi::Item::Id = -1);
  83 #else
  84 MainWindow*         displayMainWindowSelected(const QString& eventId = QString());
  85 #endif
  86 bool                readConfigWindowSize(const char* window, QSize&, int* splitterWidth = 0);
  87 void                writeConfigWindowSize(const char* window, const QSize&, int splitterWidth = -1);
  88 /** Check from its mime type whether a file appears to be a text or image file.
  89  *  If a text file, its type is distinguished.
  90  */
  91 FileType            fileType(const KMimeType::Ptr& mimetype);
  92 /** Check that a file exists and is a plain readable file, optionally a text/image file.
  93  *  Display a Continue/Cancel error message if 'errmsgParent' non-null.
  94  */
  95 enum FileErr {
  96     FileErr_None = 0,
  97     FileErr_Blank,           // generic blank error
  98     FileErr_Nonexistent, FileErr_Directory, FileErr_Unreadable, FileErr_NotTextImage,
  99     FileErr_BlankDisplay,    // blank error to use for file to display
 100     FileErr_BlankPlay        // blank error to use for file to play
 101 };
 102 FileErr             checkFileExists(QString& filename, KUrl&);
 103 bool                showFileErrMessage(const QString& filename, FileErr, FileErr blankError, QWidget* errmsgParent);
 104
 105 /** If a url string is a local file, strip off the 'file:/' prefix. */
 106 QString             pathOrUrl(const QString& url);
 107
 108 QString             browseFile(const QString& caption, QString& defaultDir, const QString& initialFile = QString(),
 109                                const QString& filter = QString(), KFile::Modes mode = 0, QWidget* parent = 0);
 110 bool                editNewAlarm(const QString& templateName, QWidget* parent = 0);
 111 void                editNewAlarm(EditAlarmDlg::Type, QWidget* parent = 0);
 112 void                editNewAlarm(KAEvent::SubAction, QWidget* parent = 0, const AlarmText* = 0);
 113 void                editNewAlarm(const KAEvent* preset, QWidget* parent = 0);
 114 void                editAlarm(KAEvent*, QWidget* parent = 0);
 115 #ifdef USE_AKONADI
 116 bool                editAlarmById(const EventId& eventID, QWidget* parent = 0);
 117 void                updateEditedAlarm(EditAlarmDlg*, KAEvent&, Akonadi::Collection&);
 118 #else
 119 bool                editAlarmById(const QString& eventID, QWidget* parent = 0);
 120 void                updateEditedAlarm(EditAlarmDlg*, KAEvent&, AlarmResource*);
 121 #endif
 122 void                viewAlarm(const KAEvent*, QWidget* parent = 0);
 123 void                editNewTemplate(EditAlarmDlg::Type, QWidget* parent = 0);
 124 void                editNewTemplate(const KAEvent* preset, QWidget* parent = 0);
 125 void                editTemplate(KAEvent*, QWidget* parent = 0);
 126 void                execNewAlarmDlg(EditAlarmDlg*);
 127 /** Create a "New From Template" QAction */
 128 KToggleAction*      createAlarmEnableAction(QObject* parent);
 129 KAction*            createStopPlayAction(QObject* parent);
 130 KToggleAction*      createSpreadWindowsAction(QObject* parent);
 131 /** Returns a list of all alarm templates.
 132  *  If shell commands are disabled, command alarm templates are omitted.
 133  */
 134 KAEvent::List       templateList();
 135 void                outputAlarmWarnings(QWidget* parent, const KAEvent* = 0);
 136 void                refreshAlarms();
 137 void                refreshAlarmsIfQueued();    // must only be called from KAlarmApp::processQueue()
 138 QString             runKMail(bool minimise);
 139
 140 #ifdef USE_AKONADI
 141 QStringList         dontShowErrors(const EventId&);
 142 bool                dontShowErrors(const EventId&, const QString& tag);
 143 void                setDontShowErrors(const EventId&, const QStringList& tags = QStringList());
 144 void                setDontShowErrors(const EventId&, const QString& tag);
 145 #else
 146 QStringList         dontShowErrors(const QString& eventId);
 147 bool                dontShowErrors(const QString& eventId, const QString& tag);
 148 void                setDontShowErrors(const QString& eventId, const QStringList& tags = QStringList());
 149 #endif
 150 void                setDontShowErrors(const QString& eventId, const QString& tag);
 151
 152 enum         // 'options' parameter values for addEvent(). May be OR'ed together.
 153 {
 154     USE_EVENT_ID       = 0x01,   // use event ID if it's provided
 155     NO_RESOURCE_PROMPT = 0x02,   // don't prompt for resource
 156     ALLOW_KORG_UPDATE  = 0x04    // allow change to be sent to KOrganizer
 157 };
 158 #ifdef USE_AKONADI
 159 UpdateStatus        addEvent(KAEvent&, Akonadi::Collection* = 0, QWidget* msgParent = 0, int options = ALLOW_KORG_UPDATE, bool showKOrgErr = true);
 160 #else
 161 UpdateStatus        addEvent(KAEvent&, AlarmResource* = 0, QWidget* msgParent = 0, int options = ALLOW_KORG_UPDATE, bool showKOrgErr = true);
 162 #endif
 163 UpdateStatus        addEvents(QVector<KAEvent>&, QWidget* msgParent = 0, bool allowKOrgUpdate = true, bool showKOrgErr = true);
 164 #ifdef USE_AKONADI
 165 bool                addArchivedEvent(KAEvent&, Akonadi::Collection* = 0);
 166 UpdateStatus        addTemplate(KAEvent&, Akonadi::Collection* = 0, QWidget* msgParent = 0);
 167 #else
 168 bool                addArchivedEvent(KAEvent&, AlarmResource* = 0);
 169 UpdateStatus        addTemplate(KAEvent&, AlarmResource* = 0, QWidget* msgParent = 0);
 170 #endif
 171 UpdateStatus        modifyEvent(KAEvent& oldEvent, KAEvent& newEvent, QWidget* msgParent = 0, bool showKOrgErr = true);
 172 UpdateStatus        updateEvent(KAEvent&, QWidget* msgParent = 0, bool archiveOnDelete = true);
 173 UpdateStatus        updateTemplate(KAEvent&, QWidget* msgParent = 0);
 174 UpdateStatus        deleteEvent(KAEvent&, bool archive = true, QWidget* msgParent = 0, bool showKOrgErr = true);
 175 #ifdef USE_AKONADI
 176 UpdateStatus        deleteEvents(QVector<KAEvent>&, bool archive = true, QWidget* msgParent = 0, bool showKOrgErr = true);
 177 UpdateStatus        deleteTemplates(const KAEvent::List& events, QWidget* msgParent = 0);
 178 inline UpdateStatus deleteTemplate(KAEvent& event, QWidget* msgParent = 0)
 179                         { KAEvent::List e;  e += &event;  return deleteTemplates(e, msgParent); }
 180 #else
 181 UpdateStatus        deleteEvents(KAEvent::List&, bool archive = true, QWidget* msgParent = 0, bool showKOrgErr = true);
 182 UpdateStatus        deleteTemplates(const QStringList& eventIDs, QWidget* msgParent = 0);
 183 inline UpdateStatus deleteTemplate(const QString& eventID, QWidget* msgParent = 0)
 184                         { return deleteTemplates(QStringList(eventID), msgParent); }
 185 #endif
 186 void                deleteDisplayEvent(const QString& eventID);
 187 #ifdef USE_AKONADI
 188 UpdateStatus        reactivateEvent(KAEvent&, Akonadi::Collection* = 0, QWidget* msgParent = 0, bool showKOrgErr = true);
 189 UpdateStatus        reactivateEvents(QVector<KAEvent>&, QVector<EventId>& ineligibleIDs, Akonadi::Collection* = 0, QWidget* msgParent = 0, bool showKOrgErr = true);
 190 UpdateStatus        enableEvents(QVector<KAEvent>&, bool enable, QWidget* msgParent = 0);
 191 QVector<KAEvent>    getSortedActiveEvents(QObject* parent, AlarmListModel** model = 0);
 192 #else
 193 UpdateStatus        reactivateEvent(KAEvent&, AlarmResource* = 0, QWidget* msgParent = 0, bool showKOrgErr = true);
 194 UpdateStatus        reactivateEvents(KAEvent::List&, QStringList& ineligibleIDs, AlarmResource* = 0, QWidget* msgParent = 0, bool showKOrgErr = true);
 195 UpdateStatus        enableEvents(KAEvent::List&, bool enable, QWidget* msgParent = 0);
 196 KAEvent::List       getSortedActiveEvents(const KDateTime& startTime = KDateTime(), const KDateTime& endTime = KDateTime());
 197 #endif
 198 void                purgeArchive(int purgeDays);    // must only be called from KAlarmApp::processQueue()
 199 void                displayUpdateError(QWidget* parent, UpdateStatus, UpdateError, int nAlarms, int nKOrgAlarms = 1, bool showKOrgError = true);
 200 void                displayKOrgUpdateError(QWidget* parent, UpdateError, UpdateStatus korgError, int nAlarms);
 201 QStringList         checkRtcWakeConfig(bool checkEventExists = false);
 202 void                deleteRtcWakeConfig();
 203 void                cancelRtcWake(QWidget* msgParent, const QString& eventId = QString());
 204 bool                setRtcWakeTime(unsigned triggerTime, QWidget* parent);
 205
 206 /** Return a prompt string to ask the user whether to convert the calendar to the
 207  *  current format.
 208  *  @param whole if true, the whole calendar needs to be converted; else only some
 209  *               alarms may need to be converted.
 210  */
 211 QString             conversionPrompt(const QString& calendarName, const QString& calendarVersion, bool whole);
 212
 213 #ifdef USE_AKONADI
 214 Akonadi::Collection invalidCollection();  // for use as a non-const default parameter
 215 #endif
 216
 217 #ifndef NDEBUG
 218 void                setTestModeConditions();
 219 void                setSimulatedSystemTime(const KDateTime&);
 220 #endif
 221
 222 } // namespace KAlarm
 223
 224 bool caseInsensitiveLessThan(const QString& s1, const QString& s2);
 225
 226 #endif // FUNCTIONS_H
 227
 228 // vim: et sw=4: