1 /*

     2 * Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description: Homescreen calendar widget's content layout handler.

    15 *

    16 */

    17 

    18 #ifndef CONTENTLAYOUTHANDLER_H

    19 #define CONTENTLAYOUTHANDLER_H

    20 

    21 // System includes

    22 #include <QObject>

    23 #include <QGraphicsLinearLayout>

    24 

    25 /*!

    26   \class AgendaUtil

    27   \brief Interface to the calendar database.

    28   \details It is used by ContentLayoutHandler to retrieve the list of calendar entries in the next seven days.\n\n

    29   <b>QList<AgendaEntry> AgendaUtil::fetchEntriesInRange(

    30             QDateTime rangeStart, QDateTime rangeEnd,

    31             AgendaUtil::FilterFlags filter = AgendaUtil::IncludeAll)</b>

    32       

    33   is the function used to retrieve the list of calendar entries in range. It returns a list of calendar events.

    34   @param rangeStart is the range date start. In calendar widget is always today.

    35   @param rangeEnd is the range date end. In calendar widget is always one week after today.

    36   @param filter is the type of event we want to include in the list. Calendar widget includes only All-Day and timed events.

    37 */

    38 

    39 // Forward declarations

    40 class AgendaEntry;

    41 class AgendaUtil;

    42 class HbDocumentLoader;

    43 class HbFrameDrawer;

    44 class HbFrameItem;

    45 class HbLabel;

    46 class HbWidget;

    47 class QGraphicsLayout;

    48 class QPointF;

    49 class QTimer;

    50 class XQServiceRequest;

    51 class XQSettingsManager;

    52 class XQSettingsKey;

    53 class TestContentLayoutHandler;

    54 class QDateTime;

    55 class QRectF;

    56 //from DateIconLayoutHandler

    57 class DateTimeObserver;

    58 /*!

    59   \class ContentLayoutHandler

    60   \brief Decorates the content layout.

    61 */

    62 // Class declaration

    63 class ContentLayoutHandler: public QObject, public QGraphicsLinearLayout

    64 {

    65     Q_OBJECT

    66     Q_PROPERTY(int testID READ testId WRITE setTestId)

    67     Q_PROPERTY(int testResult READ testResult WRITE setTestResult)

    68 

    69 public:

    70     /*! 

    71         \fn ContentLayoutHandler::ContentLayoutHandler()

    72         

    73         Constructor of the ContentLayoutHandler class.

    74      */

    75     ContentLayoutHandler();

    76     /*! 

    77         \fn ContentLayoutHandler::~ContentLayoutHandler()

    78         

    79         Destructor of the ContentLayoutHandler class.

    80      */

    81     ~ContentLayoutHandler();

    82 

    83     //Test property functions

    84     /*! 

    85         \fn int ContentLayoutHandler::testId()

    86         

    87         Used to check which test needs to run.

    88         @return Test id

    89      */

    90     int testId();

    91     /*! 

    92         \fn void ContentLayoutHandler::setTestId(int testID)

    93         

    94         Used to set which test it needs to run.

    95      */

    96     void setTestId(int testID);

    97     /*! 

    98         \fn int ContentLayoutHandler::testResult()

    99         

   100         Used to check whether the calendar has been launched correctly or not.

   101      */

   102     int testResult();

   103     /*! 

   104         \fn void ContentLayoutHandler::setTestResult(int testResult)

   105         

   106         Used to set the test property.

   107      */

   108     void setTestResult(int testResult);

   109 

   110 signals:

   111      /*! 

   112         \fn void ContentLayoutHandler::requestComplete()

   113         

   114         Emitted in case the calendar has been launched correctly.

   115      */

   116     void requestComplete();

   117     /*! 

   118         \fn void ContentLayoutHandler::requestError()

   119         

   120         Emitted in case the calendar launch didn't succeed.

   121      */

   122     void requestError();

   123     /*! 

   124         \fn void ContentLayoutHandler::currentDate(QDateTime& date)

   125         

   126         Emits the current date during layout decoration.

   127         @param date Current date

   128      */    

   129     void currentDate(QDateTime& date);

   130     

   131     //from DateIconLayoutHandler

   132     /*! 

   133         \fn void ContentLayoutHandler::dateChanged()

   134         

   135         Emitted when the date has changed.

   136      */        

   137     void dateChanged();

   138 

   139 public slots:

   140     /*! 

   141         \fn void ContentLayoutHandler::eventTimerExpired()

   142         

   143         Connected to the timer signal timeout. The timer is needed in order to calculate the time that divides

   144         the current moment from the expiration of the next upcoming event. This slot is called when the timer expires,

   145         thus, its purpose is to decorate the layout with the next upcoming event and start the timer again.

   146     */

   147     void eventTimerExpired();

   148     /*! 

   149         \fn void ContentLayoutHandler::calendarChanged(const XQSettingsKey& key, const QVariant& value)

   150         

   151         Calendar P&S listener. Its purpose is to listen to the calendar P&S in order to be notified of any calendar

   152         event modifications. Whenever it receives any notifications from the calendar, it will decorate the layout.

   153         @param key The key to listen to

   154         @param value Key value

   155     */

   156     void calendarChanged(const XQSettingsKey& key, const QVariant& value);

   157     /*! 

   158         \fn void ContentLayoutHandler::initializeLayout(const HbDocumentLoader &layoutLoader, QObject *owner)

   159         

   160         Initializes the layout using the document loader. Connected to CalendarWidget.

   161         @param layoutLoader Document loader that contains the DOCML needed to load the layout

   162         @param owner Parent

   163     */

   164     void initializeLayout(const HbDocumentLoader &layoutLoader, QObject *owner);

   165     /*! 

   166         \fn void ContentLayoutHandler::updateLayout()

   167         

   168         Decorates the layout content.

   169     */

   170     void updateLayout();

   171     /*! 

   172         \fn void ContentLayoutHandler::onThemeChange()

   173         

   174         Connected to CalendarWidget. Called when a theme change events occurs. Its purpose is to load the new

   175         theme graphics into the widget.

   176     */

   177     void onThemeChange();

   178     /*! 

   179         \fn void ContentLayoutHandler::handleOk(const QVariant& var)

   180         

   181         Connected to XQSettingsManager valueChanged signal. Called if the calendar has been launched correctly.

   182         @param var operation returning value

   183     */

   184     void handleOk(const QVariant& var);

   185     /*! 

   186         \fn void ContentLayoutHandler::handleError(int err, const QString& str)

   187         

   188         Connected to XQSettingsManager valueChanged signal. Called if the calendar has not been launched correctly.

   189         @param err Error code

   190         @param str Explanation of the error

   191     */

   192     void handleError(int err, const QString& str);

   193     /*! 

   194         \fn void ContentLayoutHandler::highlightOn(QPointF& point)

   195         

   196         Highlights the layout, if the point is inside the correct area.

   197         @param point The (scene) position of the highlighting event

   198     */

   199     void highlightOn(QPointF &point);

   200     /*! 

   201         \fn void ContentLayoutHandler::highlightOff()

   202         

   203         Removes highlighting from the layout. 

   204     */

   205     void highlightOff();

   206 

   207 private:

   208     /*! 

   209         \fn void ContentLayoutHandler::hideLabels()

   210         

   211         Called when the widget is initialized to hide all the labels in the layout. 

   212     */

   213     void hideLabels();

   214     /*! 

   215         \fn void ContentLayoutHandler::setLabelsColor()

   216         

   217         Called when the widget is initialized and when a theme change occurs to change the labels text color.

   218     */

   219     void setLabelsColor();

   220     /*! 

   221         \fn void ContentLayoutHandler::removePassedEvents()

   222         

   223         Filters out the already passed events from the list of events that comes from the calendar database.

   224     */

   225     void removePassedEvents();

   226     /*! 

   227         \fn void ContentLayoutHandler::createAgendaUtilsInstance()

   228         

   229         Initializes the agenda utils instance.

   230     */

   231     void createAgendaUtilsInstance();

   232     /*! 

   233         \fn void ContentLayoutHandler::removeTodosFrom()

   234         

   235         Filters out the todo events from the list of events that comes from the calendar database.

   236         Also filters out other type of events that should be ignored by the calendar widget.

   237     */

   238     void removeTodosFrom();

   239     /*! 

   240         \fn void ContentLayoutHandler::todayHasValidEvents()

   241         

   242         Returns true if in the list of events there are upcoming events to be shown today.

   243         Returns false otherwise.

   244     */

   245     bool todayHasValidEvents();

   246     /*! 

   247         \fn void ContentLayoutHandler::sortList()

   248         

   249         Sorts the list of events according to the starting time.

   250     */

   251     void sortList();

   252     /*! 

   253         \fn void ContentLayoutHandler::showNoEventsNextWeek()

   254         

   255         If there are no events the next seven days, decorates the layout with that information. 

   256     */

   257     void showNoEventsNextWeek();

   258     /*! 

   259         \fn void ContentLayoutHandler::showNextEvent()

   260         

   261         Decorates the layout with the information about today's next upcoming event.

   262     */

   263     void showNextEvent();

   264     /*! 

   265         \fn void ContentLayoutHandler::showOverlappingEvents(int when, int numOverlappingEvents, int aEndEventIndex)

   266         

   267         Decorates the layout with the information about how many upcoming overlapping events there are,

   268         starting time and end time.

   269         @param when 1 = today, >1 = upcoming day

   270         @param numOverlappingEvents Number of overlapping events

   271         @param aEndEventIndex The index in the list of events of the last event that overlaps the one

   272         with index 0.

   273     */

   274     void showOverlappingEvents(int when, int numOverlappingEvents, int aEndEventIndex);

   275     /*! 

   276         \fn void ContentLayoutHandler::showNextDaysEvent()

   277         

   278         Decorates the layout with the information about the next days first upcoming event.

   279     */

   280     void showNextDaysEvent();

   281     /*! 

   282         \fn int ContentLayoutHandler::checkOverlappingEvents(ulong id, int& aEndEventIndex)

   283         

   284         Calculates the number of events overlapping event with id \em id.

   285         @param id The id of the event we want to find overlapping events to

   286         @param aEndEventIndex The index of the last event that is overlapping the event id

   287         @return Number of overlapping events. 

   288     */

   289     int checkOverlappingEvents(ulong id, int& aEndEventIndex);

   290     /*! 

   291         \fn void ContentLayoutHandler::updateList()

   292         

   293         Asks calendar database to provide an updated list of events in range now, now + 7 days.

   294     */

   295     void updateList();

   296     /*! 

   297         \fn void ContentLayoutHandler::decorateContent()

   298         

   299         Contains the layout decoration logic. Called whenever an update is needed and upon widget initialization.

   300     */

   301     void decorateContent();

   302     /*! 

   303         \fn QString ContentLayoutHandler::currentDateFormat()

   304         

   305         Checks whether the current date format is english, american or 

   306         japanese and formats the date string accordingly.

   307         @return The date string formatted with the current date format

   308     */

   309     QString currentDateFormat();

   310     /*! 

   311         \fn QString ContentLayoutHandler::currentTimeFormat()

   312         

   313         Checks whether the current time format is 12 hours or 24 hours and formats the date string accordingly.

   314         @return The time string formatted with the current time format

   315     */

   316     QString currentTimeFormat();

   317     /*! 

   318         \fn int ContentLayoutHandler::timeToNextCheck()

   319         

   320         Calculates the time that needs to pass before we need to check whether a layout decoration is needed or not.

   321         @return Number of milliseconds to the next check

   322     */

   323     int timeToNextCheck();

   324     /*! 

   325         \fn int ContentLayoutHandler::initializeTimer()

   326         

   327         Initializes the timer and calculates the time to the first check.

   328     */

   329     void initializeTimer();

   330     /*! 

   331         \fn QString ContentLayoutHandler::calculateEndTime(int& aEndEventIndex)

   332         

   333         Calculates when the overlapping situation ends by checking the end 

   334         time of all the involved events and choose the biggest one.

   335         @param aEndEventIndex The index of the last overlapping event in the list of events

   336         @return The end time as a string

   337     */

   338     QString calculateEndTime(int& aEndEventIndex);

   339     /*! 

   340         \fn int ContentLayoutHandler::firstEntryIndex()

   341         

   342         Calculates the index of the first timed event in the list of events.

   343         @return The index of the first timed event

   344     */

   345     int firstEntryIndex();

   346     /*! 

   347         \fn void ContentLayoutHandler::setTimerForNextUpdate()

   348         

   349         Checks whether there are events in the list and timeToNextCheck is not zero and then sets the timer to 

   350         timeToNextCheck values.

   351     */

   352     void setTimerForNextUpdate();

   353     /*! 

   354         \fn QDateTime ContentLayoutHandler::currentDateTime()

   355         

   356         Get current date, either real device date or fake date during testing.

   357         @return Date

   358     */

   359     QDateTime currentDateTime();

   360     /*! 

   361         \fn void ContentLayoutHandler::setLabelText(HbLabel* label, QString text)

   362         

   363         Sets the label text. Checks whether the label pointer is valid or not.

   364         @param label The label to set the text to

   365         @param text The text to be set

   366     */

   367     void setLabelText(HbLabel* label, QString text);

   368     /*! 

   369         \fn void ContentLayoutHandler::setLabelVisible(HbLabel* label, bool visible)

   370         

   371         Sets visible or invisible a specified label. It checks whether the label pointer is valid or not.

   372         @param label The label to set the text to

   373         @param visible Label visible, true or false

   374     */

   375     void setLabelVisible(HbLabel* label, bool visible);

   376     /*! 

   377         \fn bool ContentLayoutHandler::isAllDayEvent(AgendaEntry entry)

   378         

   379         Checks whether a specific entry is an all day event or not.

   380         @param entry Entry to check

   381         @return True, if entry is an all day event, otherwise false

   382     */

   383     bool isAllDayEvent(AgendaEntry entry);

   384 

   385     /*! 

   386         \fn bool ContentLayoutHandler::isOneDayAllDayEvent(AgendaEntry entry)

   387             

   388         Checks whether the entry is an all day event with the duration of one day.

   389         @param entry Entry to check

   390         @return True, if entry is an one day all day event, otherwise false

   391     */

   392     bool isOneDayAllDayEvent(AgendaEntry entry);

   393     

   394     //from DateIconLayoutHandler

   395     /*! 

   396         \fn void ContentLayoutHandler::setCalendarIconContent()

   397         

   398         Updates date number label and month label texts.

   399     */    

   400     void setCalendarIconContent();

   401     /*! 

   402         \fn void ContentLayoutHandler::setLowerLabelOverlapping(int numberOfEvents)

   403         

   404         Sets the lower label text to indicate overlapping events.

   405         @param numberOfEvents Number of overlapping events to insert in the localized text

   406     */

   407     void setLowerLabelOverlapping(int numberOfEvents);

   408     

   409 private: // data

   410     Q_DISABLE_COPY(ContentLayoutHandler)

   411 

   412     HbWidget* mContainer;

   413 

   414     HbLabel* mReminderLabel;

   415     HbLabel* mUpperLabelShort;

   416     HbLabel* mUpperLabelLong;

   417     HbLabel* mMiddleLabel;

   418     HbLabel* mLowerLabel;

   419     

   420     //From DateIconLayoutHandler

   421     // Containers

   422     HbWidget* mIconContainer;

   423     

   424     // Labels (not owned)

   425     HbLabel* mIconLabel;

   426     HbLabel* mNumberLabel;

   427     HbLabel* mMonthLabel;

   428     HbLabel* mHighlightLabel;

   429         

   430     // Background drawer (not owned)

   431     HbFrameDrawer* mDateIconFrameDrawer;

   432 

   433     // Owned

   434     DateTimeObserver* mDateObserver;

   435     //From MainLayoutHandler

   436     HbWidget* mWidget;

   437 

   438     // Background label

   439     HbLabel* mBgLabel;

   440     

   441     // Separator

   442     HbLabel* mSeparatorLabel;

   443 

   444     //to paint icon and widget background

   445     HbFrameItem* mIconLayoutItem;

   446     HbFrameItem* mBackgroundLayoutItem;

   447     HbFrameItem* mSeparatorLayoutItem;

   448     //END

   449     // Frame drawer for reminder icon (not owned)

   450     HbFrameDrawer* mReminderDrawer;

   451     //timer used to know when the current shown event disappears

   452     QTimer* mEventTimer;

   453 

   454     //Agenda Utils

   455     AgendaUtil* mAgendaUtil;

   456     QList<AgendaEntry> mAgendaEntryList;

   457     XQSettingsManager* mCalendarKeyManager;

   458 

   459     // State variables

   460     bool mDateHighlightActive;

   461     bool mContentHighlightActive;

   462     

   463     //test variables

   464     int mTestID;

   465     int mTestResult;

   466 

   467     friend class TestContentLayoutHandler;

   468 };

   469 

   470 #endif // CONTENTLAYOUTHANDLER_H