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 screensavers.

    15 *

    16 */

    17 

    18 #include "screensaver.h"

    19 #include "screensaver_p.h"

    20 

    21 /*!

    22     \enum ScreensaverState

    23     Lists states that the Screensaver can be in.

    24 */

    25 

    26 /*

    27     \var ScreensaverState ScreensaverStateConstructed

    28     Screensaver is in this state right after construction.

    29 */

    30 

    31 /*

    32     \var ScreensaverState ScreensaverStateInitialized

    33 

    34     All Screensaver resources are initialized.

    35     Screensaver is set to Initialized state after a call to initialize 

    36     (if previously Constructed or Closed) method.

    37 */

    38 

    39 /*

    40     \var Screensaver ScreensaverStateBackground

    41     Screensaver is in background, its operations are suspended.

    42     Screensaver is set to Background after a call to background method.

    43 */

    44 

    45 /*

    46     \var Screensaver ScreensaverStateForeground 

    47     Screensaver is in foreground and fully operational, showing the main visualization.

    48     Screensaver is set to Foreground after a call to foreground method.

    49 */

    50 

    51 /*

    52     \var Screensaver ScreensaverStatePartialForeground 

    53     Screensaver has limited foreground (in OLED display cases).

    54     Screensaver is set to PartialForeground after a call to partialForeground method.

    55 */

    56 

    57 /*

    58     \var Screensaver ScreensaverStatePowerSave 

    59     Device is in power save mode. Screensaver should limit all processing.

    60     Screensaver is set to PowerSave after a call to powerSave method.

    61 */

    62 

    63 /*

    64     \var Screensaver ScreensaverStateClosed 

    65     Screensaver is closed. All resources should be frees.

    66     Screensaver is set to Closed after a call to close method.

    67 */

    68 

    69 /*!

    70     \class Screensaver

    71     \brief Base class for all screensavers.

    72 

    73     Screensaver plug-ins provide the visualizations for different screensaver application states.

    74     A Screensaver is notified about state changes and in consequence it should emit a signal

    75     viewChanged() carrying a QGraphicsWidget which will be set as the current view.

    76     The application takse care about tracing device status so the Screensaver should be only

    77     concerned about the GUI.

    78  */

    79 

    80 /*!

    81     Constructs a new Screensaver with \a parent.

    82  */

    83 Screensaver::Screensaver(QObject *parent) :

    84     QObject(parent), m_d(new ScreensaverPrivate(this))

    85 {

    86 }

    87 

    88 /*!

    89     Destructs the class.

    90  */

    91 Screensaver::~Screensaver()

    92 {

    93     delete m_d;

    94 }

    95 

    96 /*!

    97     \fn void Screensaver::faulted()

    98 

    99     This signal is emitted if a fault occurs when changing Screensaver's state.

   100  */

   101 

   102 /*!

   103     \fn void Screensaver::viewChanged(QGraphicsWidget *widget)

   104 

   105     This signal should be emitted when the Screensaver needs to change its visualization

   106     after a state change.

   107     \param widget The graphics widget container holding the current visualization.

   108  */

   109 

   110 /*!

   111     Returns the state that the Screensaver is currently in.

   112     \return The current state.

   113  */

   114 ScreensaverState Screensaver::currentState()

   115 {

   116     return m_d->currentState();

   117 }

   118 

   119 /*!

   120     Initializes the Screensaver

   121  */

   122 void Screensaver::initialize()

   123 {

   124     m_d->initialize();

   125 }

   126 

   127 /*!

   128     Called when the application is in foreground.

   129  */

   130 void Screensaver::foreground()

   131 {

   132     m_d->foreground();

   133 }

   134 

   135 /*!

   136     Called when the application gains limited foreground as with OLED display cases.

   137  */

   138 void Screensaver::partialForeground()

   139 {

   140     m_d->partialForeground();

   141 }

   142 

   143 /*!

   144     Called when the application goes to background.

   145  */

   146 void Screensaver::background()

   147 {

   148     m_d->background();

   149 }

   150 

   151 /*!

   152     Called when device enters power save mode.

   153  */

   154 void Screensaver::powerSave()

   155 {

   156     m_d->powerSave();

   157 }

   158 

   159 /*!

   160     Stops Screensaver's processing.

   161  */

   162 void Screensaver::close()

   163 {

   164     m_d->close();

   165 }

   166 

   167 /*!

   168     If there is any active universal indicator when screensaver

   169     is launched, then this method is called.

   170     Note that indicators are implemented only for Symbian/S60 OS.

   171     \param activeIndicators List of currently active indicators in 

   172     the chronological order according to their arrival time.

   173  */

   174 void Screensaver::handleActiveIndicators(

   175     const QList<HbIndicatorInterface*> &activeIndicators)

   176 {

   177     // TODO: need to go through private class?

   178     m_d->handleActiveIndicators(activeIndicators);

   179 }

   180 

   181 /*!

   182     Called when some universal indicator is activated.

   183     \param activatedIndicator Activated indicator. Ownership is not transferred.

   184  */

   185 void Screensaver::handleActivatedIndicator(

   186     HbIndicatorInterface* activatedIndicator)

   187 {

   188     m_d->handleActivatedIndicator(activatedIndicator);

   189 }

   190 

   191 /*!

   192     Called when some universal indicator is deactivated.

   193     \param activatedIndicator Deactivated indicator. Ownership is not transferred.

   194  */

   195 void Screensaver::handleDeactivatedIndicator(

   196     HbIndicatorInterface* deactivatedIndicator)

   197 {

   198     m_d->handleDeactivatedIndicator(deactivatedIndicator);

   199 }

   200 

   201 

   202 /*!

   203     \fn virtual bool Screensaver::onForeground() = 0

   204 

   205     After a call the Screensaver should emit the foreground state visualization.

   206     Returns true if the operation secceeded, otherwise false - in this case 

   207     the faulted() signal will be emitted by the base class.

   208     \return Indicates if the operation succeeded.

   209  */

   210 

   211 /*!

   212     \fn virtual bool Screensaver::onPartialForeground() = 0

   213 

   214     After a call the Screensaver should emit the partial foreground state visualization.

   215     This is valid for OLED display cases when the screensaver is displayed at all times

   216     with limited functionality.

   217     Returns true if the operation secceeded, otherwise false - in this case 

   218     the faulted() signal will be emitted by the base class.

   219     \return Indicates if the operation succeeded.

   220  */

   221 

   222 /*!

   223     \fn virtual bool Screensaver::onBackground() = 0

   224 

   225     After a call the Screensaver should limit its processing.

   226     Returns true if the operation secceeded, otherwise false - in this case 

   227     the faulted() signal will be emitted by the base class.

   228     \return Indicates if the operation succeeded.

   229  */

   230 

   231 /*!

   232     \fn virtual bool Screensaver::onPowerSave() = 0

   233 

   234     After a call the Screensaver should limit its processing as much as possible.

   235     Returns true if the operation secceeded, otherwise false - in this case 

   236     the faulted() signal will be emitted by the base class.

   237     \return Indicates if the operation succeeded.

   238  */

   239 

   240 /*!

   241     After a call it should initialize the Screensaver.

   242     Returns true if the operation secceeded, otherwise false - in this case 

   243     the faulted() signal will be emitted by the base class.

   244     The default implementation does nothing and always returns true.

   245     \return Indicates if the operation succeeded.

   246  */

   247 bool Screensaver::onInitialize()

   248 {

   249     return true;

   250 }

   251 

   252 /*!

   253     After a call it should close the Screensaver.

   254     The Screensaver should also free all resources.

   255     Returns true if the operation secceeded, otherwise false - in this case 

   256     the faulted() signal will be emitted by the base class.

   257     The default implementation does nothing and always returns true.

   258     \return Indicates if the operation succeeded.

   259  */

   260 bool Screensaver::onClose()

   261 {

   262     return true;

   263 }

   264 

   265 /*!

   266     The default implementation is empty.

   267  */

   268 void Screensaver::onHandleActiveIndicators(

   269         const QList<HbIndicatorInterface*> &activeIndicators)

   270 {

   271     Q_UNUSED(activeIndicators);

   272 }

   273 

   274 /*!

   275     The default implementation is empty.

   276  */

   277 void Screensaver::onHandleActivatedIndicator(

   278         HbIndicatorInterface *activatedIndicator)

   279 {

   280     Q_UNUSED(activatedIndicator);

   281 }

   282 

   283 /*!

   284     The default implementation is empty.

   285  */

   286 void Screensaver::onHandleDeactivatedIndicator(

   287         HbIndicatorInterface *deactivatedIndicator)

   288 {

   289     Q_UNUSED(deactivatedIndicator);

   290 }

   291