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:  Base class for all homescreen widgets.

    15 *

    16 */

    17 #include <QGraphicsDropShadowEffect>

    18 

    19 #include "hswidget.h"

    20 #include "hswidget_p.h"

    21 #include "ihswidgetpreferenceservice.h"

    22 

    23 /*DEPRECATED

    24     \ingroup group_hswidgetmodel group_widget_api_candidates

    25     \class HsWidget

    26     \brief Base class for all home screen widgets.

    27 

    28     Widget base class declares automata for derived widget. It also overwrites

    29     mouse event functions to enable all mouse events.

    30 */

    31 

    32 /*!

    33     \enum HsWidget::StartResult

    34     

    35     Return values for onStart() method.

    36 */

    37 

    38 /*!

    39     \enum HsWidget::StopResult

    40     

    41     Return values for onSuspend() method.

    42 */

    43 /*!

    44     \enum HsWidget::SuspendResult

    45     

    46     Return values for onSuspend() method.

    47 */

    48 

    49 /*!

    50     \enum HsWidget::ResumeResult

    51     

    52     Return values for onResume() method.

    53 */

    54 

    55 

    56 const char WIDGET_PREFERENCE_SERVICE_KEY[]="http://homescreen.nokia.com/runtimeservices/widgetpreferenceservice";

    57 

    58 

    59 HsWidgetPrivate::HsWidgetPrivate(HsWidget* handle): 

    60     mPublic(handle),

    61     mState(WidgetStateConstructed)

    62 {

    63 

    64 }

    65 

    66 HsWidgetPrivate::~HsWidgetPrivate()

    67 {

    68 

    69 }

    70 

    71 void HsWidgetPrivate::start()

    72 {

    73     switch(mState)

    74     {

    75     case WidgetStateConstructed:

    76     case WidgetStateFinished:

    77         break;

    78 

    79     default:

    80         return;

    81     }

    82 

    83     switch(mPublic->onStart())

    84     {

    85     case HsWidget::StartResultRunning:

    86         mState = WidgetStateRunning;

    87         break;

    88 

    89     case HsWidget::StartResultFinished:

    90         mState = WidgetStateFinished;

    91         emit mPublic->succeeded();

    92         break;

    93 

    94     case HsWidget::StartResultFaulted:

    95         mState = WidgetStateFinished;

    96         emit mPublic->faulted();

    97         break;

    98     }

    99 }

   100 

   101 

   102 void HsWidgetPrivate::stop()

   103 {

   104     switch(mState)

   105     {

   106     case WidgetStateRunning:

   107     case WidgetStateSuspended:

   108         break;

   109 

   110     default:

   111         return;

   112     }

   113 

   114     switch(mPublic->onStop())

   115     {

   116     case HsWidget::StopResultFinished:

   117         mState = WidgetStateFinished;

   118         emit mPublic->stopped();

   119         break;

   120 

   121     case HsWidget::StopResultFinishing:

   122         mState = WidgetStateFinishing;

   123         break;

   124 

   125     case HsWidget::StopResultFaulted:

   126         mState = WidgetStateFinished;

   127         emit mPublic->faulted();

   128         break;

   129 

   130     case HsWidget::StopResultFaulting:

   131         mState = WidgetStateFaulting;

   132         break;

   133     }

   134 }

   135 

   136 

   137 void HsWidgetPrivate::suspend()

   138 {

   139     switch(mState)

   140     {

   141     case WidgetStateRunning:

   142         break;

   143 

   144     default:

   145         return;

   146     }

   147 

   148     switch(mPublic->onSuspend())

   149     {

   150     case HsWidget::SuspendResultSuspended:

   151         mState = WidgetStateSuspended;

   152         break;

   153 

   154     case HsWidget::SuspendResultFaulted:

   155         mState = WidgetStateFinished;

   156         emit mPublic->faulted();

   157         break;

   158 

   159     case HsWidget::SuspendResultFaulting:

   160         mState = WidgetStateFaulting;

   161         break;

   162     }

   163 }

   164 

   165 void HsWidgetPrivate::resume()

   166 {

   167     switch(mState)

   168     {

   169     case WidgetStateSuspended:

   170         break;

   171 

   172     default:

   173         return;

   174     }

   175 

   176     switch(mPublic->onResume())

   177     {

   178     case HsWidget::ResumeResultRunning:

   179         mState = WidgetStateRunning;

   180         break;

   181 

   182     case HsWidget::ResumeResultFaulted:

   183         mState = WidgetStateFinished;

   184         emit mPublic->faulted();

   185         break;

   186 

   187     case HsWidget::ResumeResultFaulting:

   188         mState = WidgetStateFaulting;

   189         break;

   190     }

   191 }

   192 

   193 

   194 void HsWidgetPrivate::setFinished()

   195 {

   196     switch(mState)

   197     {

   198     case WidgetStateConstructed:

   199     case WidgetStateFinished:

   200         return;

   201 

   202     case WidgetStateRunning:

   203         mState = WidgetStateFinished;

   204         emit mPublic->succeeded();

   205         break;

   206 

   207     case WidgetStateSuspended:

   208         mState = WidgetStateFinished;

   209         emit mPublic->succeeded();

   210         break;

   211 

   212     case WidgetStateFinishing:

   213         mState = WidgetStateFinished;

   214         emit mPublic->stopped();

   215         break;

   216 

   217     case WidgetStateFaulting:

   218         mState = WidgetStateFinished;

   219         emit mPublic->faulted();

   220         break;

   221     }

   222 }

   223 

   224 

   225 void HsWidgetPrivate::setFaulted()

   226 {

   227     switch(mState)

   228     {

   229     case WidgetStateConstructed:

   230     case WidgetStateFinished:

   231         return;

   232 

   233     default:

   234         break;

   235     }

   236 

   237     mState = WidgetStateFinished;

   238     emit mPublic->faulted();

   239 }

   240 

   241 

   242 void HsWidgetPrivate::setFaulting()

   243 {

   244     switch(mState)

   245     {

   246     case WidgetStateConstructed:

   247     case WidgetStateFinished:

   248     case WidgetStateFaulting:

   249         return;

   250 

   251     default:

   252         break;

   253     }

   254 

   255     mState = WidgetStateFaulting;

   256 }

   257 /*!

   258     Constructs a widget which is a child of \a parent, with widget flags set to \a flags.

   259     

   260 */

   261 HsWidget::HsWidget(QGraphicsItem *parent, Qt::WindowFlags flags)

   262     : HbWidget(parent, flags),mD(new HsWidgetPrivate(this))

   263 {   

   264 }

   265 

   266 /*!

   267     Destructor

   268     

   269 */

   270 HsWidget::~HsWidget()

   271 {

   272     delete mD;

   273 }

   274 /*!

   275     Convenience method that returns the widget preference service from dynamically

   276     added meta object property.

   277 */

   278 

   279 IHsWidgetPreferenceService* HsWidget::widgetPreferenceService() const

   280 {

   281     return property(WIDGET_PREFERENCE_SERVICE_KEY).

   282         value<IHsWidgetPreferenceService*>();

   283 }

   284 

   285 /*!

   286     Widget runtime starts widget

   287 */

   288 void HsWidget::start()

   289 {

   290     mD->start();

   291 }

   292 

   293 /*!

   294     Widget runtime stops widget

   295 */

   296 void HsWidget::stop()

   297 {

   298     mD->stop();

   299 }

   300 

   301 /*!

   302     Widget runtime suspends widget

   303 */

   304 void HsWidget::suspend()

   305 {

   306     mD->suspend();

   307 }

   308 

   309 /*!

   310     Widget runtime resumes widget

   311 */

   312 void HsWidget::resume()

   313 {

   314     mD->resume();

   315 }

   316 

   317 /*!

   318     \fn void HsWidget::succeeded()

   319   

   320     Emitted after this widget has succesfully done its job

   321 */

   322 

   323 /*!

   324     \fn void HsWidget::stopped()

   325     

   326     Emitted after this widget has stopped

   327 */

   328 

   329 /*!

   330     \fn void HsWidget::faulted()

   331   

   332     Emitted after this widget has faulted

   333 */

   334 

   335 /*!

   336     \fn virtual StartResult HsWidget::onStart() = 0

   337     

   338     WIdget can now e.g restore preferences

   339 */

   340 

   341 /*!

   342     \fn virtual StopResult HsWidget::onStop() = 0

   343     

   344     Release resources. Widget will be destroyed.

   345 */

   346 

   347 /*!

   348     Called by the widget runtime. Suspends this widget.

   349 */

   350 HsWidget::SuspendResult HsWidget::onSuspend()

   351 {

   352     return SuspendResultSuspended;

   353 }

   354 

   355 /*!

   356     Called by the widget runtime. Resumes this widget.

   357 */

   358 HsWidget::ResumeResult HsWidget::onResume()

   359 {

   360     return ResumeResultRunning;

   361 }

   362 

   363 /*!

   364     Indicates to the widget runtime that this widget should

   365     transition to the Finished state.

   366 */

   367 void HsWidget::setFinished()

   368 {

   369     mD->setFinished();

   370 }

   371 

   372 /*!

   373     Indicates to the widget runtime that this widget should

   374     transition to the Faulted state.

   375 */

   376 void HsWidget::setFaulted()

   377 {

   378     mD->setFaulted();

   379 }

   380 

   381 /*!

   382     Indicates to the widget runtime that this widget should

   383     transition to the Faulting state.

   384 */

   385 void HsWidget::setFaulting()

   386 {

   387     mD->setFaulting();

   388 }

   389 

   390 

   391 

   392