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: Example of home screen widget

    15 *

    16 */

    17 

    18 

    19 #include <QGraphicsProxyWidget>

    20 #include <QPushButton>

    21 #include "helloworldwidget.h"

    22 

    23 /*!

    24 

    25 

    26 @page page_developing_home_screen_widget Creating Home Screen Widget

    27 

    28 <b>Since the home screen widget concept is still open, these APIs may still be subject to changes and additions.</b>

    29 

    30 Creating a home screen widget includes the following three steps:

    31 

    32 <ul>

    33   <li> @ref page_developing_home_screen_widget </li>

    34   <li> @ref page_creating_widget_provider </li>

    35   <li> @ref page_deploying_widget_provider </li>

    36 </ul>

    37 

    38 Each home screen widget is inherited from HsWidget base class and HsWidget itself inherits HbWidget.

    39 Usually you need to re-implement \c paint, \c boundingRect and \c shape functions from QGraphicsWidget

    40 and HsWidget::onStart, HsWidget::onStop, HsWidget::onSuspend, HsWidget::onResume functions 

    41 from HsWidget.

    42 

    43 Instructions how to add widget to provider plugin can be found from @ref page_creating_widget_provider.

    44 

    45 See @ref section_widget_state_machine for widget life cycle in detail.

    46 

    47 The steps to create a widget are:

    48 <ol>

    49 <li> Declare a widget class that inherits from \c HsWidget.

    50 

    51 <li> Implement constructor for the class where needed children are created.

    52 

    53 <li> Implement destructor.

    54 

    55 <li> Implement HsWidget::onStart() function. This is called by widget runtime to start the widget.

    56 

    57 <li> Implement HsWidget::onStop() function. When called widget should stop all the processing started in \c onStart() function.

    58 

    59 <li> Implement HsWidget::onSuspend() if needed.

    60 

    61 <li> Implement HsWidget::onResume() if needed.

    62 

    63 </ol>

    64 

    65 Example of the home screen widget is HelloWorldWidget.

    66 

    67 

    68 @section section_widget_resources Widget resources

    69 

    70 Currently widgets are lacking of a unified way to handle widget resources.

    71 This functionality will be added in the near future. Meanwhile we recommend using compiled-in resources.

    72 How to do it is explained <a href="http://doc.trolltech.com/4.5/resources.html">here</a>.

    73 

    74 */

    75 

    76 /*!

    77 

    78     \ingroup group_helloworld_widget

    79     \class HelloWorldWidget

    80     \brief Example implementation for home screen widget.

    81 

    82     HelloWorldWidget derived from the HsWidget and implements 

    83     needed functions for the home screen widget. 

    84     

    85     

    86     

    87 */

    88 

    89 

    90 /*!

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

    92 */

    93 HelloWorldWidget::HelloWorldWidget(QGraphicsItem* parent, Qt::WindowFlags flags)

    94     : HsWidget(parent, flags),

    95       mButton(0)

    96 {

    97     QGraphicsProxyWidget *proxy = new QGraphicsProxyWidget(this);

    98     mButton = new QPushButton("Hello World");

    99     proxy->setWidget(mButton);        

   100 }

   101 

   102 /*!

   103     Destructor

   104 */

   105 HelloWorldWidget::~HelloWorldWidget()

   106 {

   107 

   108 }

   109 

   110 /*!

   111     Return bounding rect

   112 */

   113 QRectF HelloWorldWidget::boundingRect() const

   114 {

   115     return childrenBoundingRect();

   116 }

   117 

   118 /*!

   119     Return shape

   120 */

   121 QPainterPath HelloWorldWidget::shape() const

   122 {   

   123     QPainterPath path;

   124     path.addRect(boundingRect());

   125     return path;

   126 }

   127 

   128 /*!

   129     Widget runtime starts widget

   130 */

   131 HsWidget::StartResult HelloWorldWidget::onStart()

   132 {

   133     return StartResultRunning;

   134 }

   135 

   136 /*!

   137     Widget runtime stops widget

   138 */

   139 HsWidget::StopResult HelloWorldWidget::onStop()

   140 {

   141     return StopResultFinished;

   142 }

   143 

   144 /*!

   145     Widget runtime suspends widget

   146 */

   147 HsWidget::SuspendResult HelloWorldWidget::onSuspend()

   148 {

   149     return SuspendResultSuspended;

   150 }

   151 

   152 /*!

   153     Widget runtime resumes widget

   154 */

   155 HsWidget::ResumeResult HelloWorldWidget::onResume()

   156 {

   157     return ResumeResultRunning;

   158 }