← Back to branch summary

~ubuntu-branches/ubuntu/utopic/kde-workspace/utopic-proposed

« back to all changes in this revision

Viewing changes to plasma/generic/dataengines/calendar/calendarengine.h

  • Committer: Bazaar Package Importer
  • Author(s): Michał Zając
  • Date: 2011-07-09 08:31:15 UTC
  • Revision ID: james.westby@ubuntu.com-20110709083115-ohyxn6z93mily9fc
Tags: upstream-4.6.90
Import upstream version 4.6.90

Show diffs side-by-side

added added

removed removed

Lines of Context:
plasma/generic/dataengines/calendar/calendarengine.h
 
1
/*
 
2
    Copyright (c) 2009 Davide Bettio <davide.bettio@kdemail.net>
 
3
    Copyright (c) 2010 Frederik Gladhorn <gladhorn@kde.org>
 
4
 
 
5
    This library is free software; you can redistribute it and/or modify it
 
6
    under the terms of the GNU Library General Public License as published by
 
7
    the Free Software Foundation; either version 2 of the License, or (at your
 
8
    option) any later version.
 
9
 
 
10
    This library is distributed in the hope that it will be useful, but WITHOUT
 
11
    ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 
12
    FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
 
13
    License for more details.
 
14
 
 
15
    You should have received a copy of the GNU Library General Public License
 
16
    along with this library; see the file COPYING.LIB.  If not, write to the
 
17
    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
 
18
    02110-1301, USA.
 
19
*/
 
20
 
 
21
 
 
22
#ifndef CALENDARENGINE_H
 
23
#define CALENDARENGINE_H
 
24
 
 
25
#include <Plasma/DataEngine>
 
26
 
 
27
namespace CalendarSupport {
 
28
    class Calendar;
 
29
}
 
30
 
 
31
namespace KHolidays
 
32
{
 
33
    class HolidayRegion;
 
34
} // namespace KHolidays
 
35
 
 
36
/**
 
37
    The calendar data engine delivers calendar events.
 
38
    It can be queried for holidays or the akonadi calendar.
 
39
 
 
40
    Supported Holiday requests are:
 
41
 
 
42
        holidaysRegions
 
43
            * Returns a list of available Holiday Region Codes
 
44
        holidaysDefaultRegion
 
45
            * Returns a QString of a sensible default Holiday Region
 
46
        holdaysIsValidRegion:[regionCode]
 
47
            * Returns a bool if given Holiday Region is valid
 
48
        holdaysRegion:[regionCode(s)]
 
49
            * Returns the details of the Holiday Regions
 
50
        holidays:[regionCode(s)]:[YYYY-MM-DD]:[YYYY-MM-DD]
 
51
            * Returns a QList of all holidays in a Holiday Region(s) between two given dates.
 
52
        holidays:[regionCode(s)]:[YYYY-MM-DD]
 
53
            * Returns a QList of all holidays  in a Holiday Region(s) on a given day
 
54
        holidaysInMonth:[regionCode(s)]:[YYYY-MM-DD]
 
55
            * Returns a QList of all holidays in a Holiday Region(s) in a given month
 
56
        isHoliday:[regionCode(s)]:[YYYY-MM-DD]
 
57
            * Returns a bool if a given date is a Holiday in the given Holiday Region(s)
 
58
        description:[regionCode(s)]:[YYYY-MM-DD]
 
59
            * Returns a QString of all holiday names in a given Holiday Region(s) on a given date
 
60
 
 
61
    Where valid, regionCode(s) are a comma separated list of one or more valid Holiday Regions
 
62
 
 
63
    Each Holiday Region is a pair of a QString containing the regionCode and a Data containing value
 
64
    pairs for:
 
65
        "Name"                      Name of the Holiday Region          String
 
66
        "Description"               The description  of the Region      String
 
67
        "CountryCode"               The country code of the Region      String, ISO 3166-2 format
 
68
        "Location"                  The location of the Region          String, ISO 3166-1 format
 
69
        "LanguageCode"              The language of the Region          String, ISO 639-1 format
 
70
 
 
71
    Each Holiday is a Data containing QString value pairs for:
 
72
        "Name"                      Name of holiday                     String
 
73
        "RegionCode"                The Holiday Region code             String
 
74
        "ObservanceStartDate"       The start date of the holiday       ISO format Gregorian date
 
75
        "ObservanceEndDate"         The end date of the holiday         ISO format Gregorian date
 
76
        "ObservanceDuration"        How many days the holiday lasts     Integer
 
77
        "ObservanceType"            If the holiday is a day off         "PublicHoliday", "Other"
 
78
 
 
79
    Note that multiple holidays can be returned for each date.
 
80
 
 
81
    Supported Akonadi requests are:
 
82
 
 
83
        eventsInMonth:[YYYY-MM-DD]
 
84
        events:[YYYY-MM-DD]:[YYYY-MM-DD]
 
85
        events:[YYYY-MM-DD]
 
86
 
 
87
        The returned data contains (not all fields guaranteed to be populated):
 
88
 
 
89
            "UID"                     QString
 
90
            "Type"                    QString        "Event", "Todo", Journal"
 
91
            "Summary"                 QString
 
92
            "Comments"                QStringList
 
93
            "Location"                QString
 
94
            "OrganizerName"           QString
 
95
            "OrganizerEmail"          QString
 
96
            "Priority"                int
 
97
            "StartDate"               KDateTime
 
98
            "EndDate"                 KDateTime
 
99
            "RecurrenceDates"         QList(QVariant(KDateTime))
 
100
            "Recurs"                  bool
 
101
            "AllDay"                  bool
 
102
            "Categories"              QStringList
 
103
            "Resources"               QStringList
 
104
            "DurationDays"            int
 
105
            "DurationSeconds"         int
 
106
            "Status"                  QString         "None", "Tentative", "Confirmed", "Draft",
 
107
                                                      "Final", "Completed", "InProcess",
 
108
                                                      "Cancelled", "NeedsAction", "NonStandard",
 
109
                                                      "Unknown"
 
110
            "StatusName"              QString         translated Status
 
111
            "Secrecy"                 QString         "Public", "Private", "Confidential", "Unknown"
 
112
            "SecrecyName"             QString         translated Secrecy
 
113
            "Occurrences"             QList(QVariant(Plasma::DataEngine::Data))
 
114
                where each Data contains details of an occurence of the event:
 
115
                    "OccurrenceUid"          QString      for convenience, same as UID
 
116
                    "OccurrenceStartDate"    KDateTime
 
117
                    "OccurrenceEndDate"      KDateTime
 
118
 
 
119
        Event type specific data keys:
 
120
            "EventMultiDay"           bool
 
121
            "EventHasEndDate"         bool
 
122
            "EventTransparency"       QString         "Opaque", "Transparent", "Unknown"
 
123
 
 
124
        Todo type specific data keys:
 
125
            "TodoHasStartDate"        bool
 
126
            "TodoIsOpenEnded"         bool
 
127
            "TodoHasDueDate"          bool
 
128
            "TodoDueDate"             KDateTime
 
129
            "TodoIsCompleted"         bool
 
130
            "TodoIsInProgress"        bool
 
131
            "TodoIsNotStarted"        bool
 
132
            "TodoPercentComplete"     int
 
133
            "TodoHasCompletedDate"    bool
 
134
            "TodoCompletedDate"       bool
 
135
 
 
136
        Fields still to be done:
 
137
            Attendees
 
138
            Attachments
 
139
            Relations
 
140
            Alarms
 
141
            Custom Properties
 
142
            Lat/Lon
 
143
            Collection/Source
 
144
 
 
145
*/
 
146
class CalendarEngine : public Plasma::DataEngine
 
147
{
 
148
    Q_OBJECT
 
149
 
 
150
    public:
 
151
        CalendarEngine( QObject* parent, const QVariantList& args );
 
152
        ~CalendarEngine();
 
153
 
 
154
    protected:
 
155
        /// general request for data from this data engine
 
156
        bool sourceRequestEvent(const QString &name);
 
157
 
 
158
    private:
 
159
        /// a request for holidays data
 
160
        bool holidayCalendarSourceRequest(const QString& key, const QStringList& args, const QString& request);
 
161
 
 
162
        /// a request for data that comes from akonadi
 
163
        /// creates EventDataContainers as needed
 
164
        bool akonadiCalendarSourceRequest(const QString& key, const QStringList& args, const QString& request);
 
165
 
 
166
        /// this will start akonadi if necessary and init m_calendarModel
 
167
        void initAkonadiCalendar();
 
168
 
 
169
        /// this is the representation of the root calendar itself. it contains everything (calendars, incidences)
 
170
        CalendarSupport::Calendar *m_calendar;
 
171
 
 
172
        /// holiday calendar
 
173
        QHash<QString, KHolidays::HolidayRegion *> m_regions;
 
174
        QString m_defaultHolidayRegion; // Cached value of default holiday region
 
175
        QString m_defaultHolidayRegionCountry; // The locale country when the cached default calculated
 
176
        QString m_defaultHolidayRegionLanguage; // The locale language when the cached default calculated
 
177
};
 
178
 
 
179
K_EXPORT_PLASMA_DATAENGINE(calendar, CalendarEngine)
 
180
 
 
181
#endif