1 /*

     2 * Copyright (c) 2010 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 localised home screen widget

    15 *

    16 */

    17 

    18 #include <qserviceinterfacedescriptor.h>

    19 #include <qabstractsecuritysession.h>

    20 #include <qservicecontext.h>

    21 

    22 #include "localisedhellowidgetplugin.h"

    23 #include "localisedhellowidget.h"

    24 

    25 /**

    26     @page page_creating_widget_plugin Creating Home Screen Widget Plugin

    27 

    28     Widgets are exposed to the home screen through QT Service Framework.

    29     Widget plugins are implemented according to

    30     <a href="http://qt.nokia.com/doc/qtmobility-1.0-tp/service-frameworks.html">Qt service framework plugin model</a>.

    31 

    32     See @ref page_nativewidgetmodel for the instructions how to create widget for the home screen.

    33 

    34     The steps to create a widget plugin are:

    35     <ol>

    36     <li> Declare a plugin class that inherits from QObject and from the \c QServicePluginInterface interface.

    37     

    38     <li> Use the Q_INTERFACES() macro to tell Qt's meta-object system about the \c QServicePluginInterface interface.

    39     

    40     <li> Export the plugin using the Q_EXPORT_PLUGIN2() macro.

    41     

    42     <li> Build the plugin using an suitable .pro file. See @ref page_deploying_widget_plugin

    43     </ol>

    44     

    45     An example (full example source code can be found from section @ref page_nativewidgetmodel):

    46 

    47     Each widget plugin has a XML file that allows searching widgets through QT service framework without first loading it.

    48     The XML file contains information on widgets inside the plugin:

    49     

    50     \li \c name             The name of the plugin binary.

    51     \li \c filepath         The absolute path and name of plugin without suffix

    52     \li \c interface name   Uniquely identifies the widget.

    53     \li \c title            Widget's human-readable name.

    54     \li \c iconuri          URI of the widget's icon image file.

    55     

    56     Example: XML for a widget plugin.

    57     

    58     @code

    59     <?xml version="1.0" encoding="UTF-8"?>

    60     <service>

    61         <name>helloworldwidgetplugin</name>

    62         <filepath>helloworldwidgetplugin</filepath>

    63         <description>Example widget</description>

    64         <interface>

    65             <name>com.nokia.symbian.IHomeScreenWidget</name>

    66             <version>1.0</version>

    67             <description>Example of home screen widget</description>

    68             <capabilities></capabilities>

    69             <customproperty key="iconuri">helloworldwidgetplugin.png</customproperty>

    70             <customproperty key="title">HelloWorld</customproperty>

    71         </interface>

    72     </service>

    73     @endcode

    74 */

    75 

    76 /**

    77     @page page_deploying_widget_plugin Deploying Home Screen Widget Plugin

    78     

    79     Widget's binaries and xml file(s) must be deployed to correct folders on emulator and in target. 

    80     Below are the needed .pro file for the \c helloworldwidgetplugin.

    81     

    82     For example:

    83     

    84     @code

    85     # helloworldwidgetplugin.pro

    86 

    87     TEMPLATE = lib

    88     CONFIG += plugin mobility hb

    89     MOBILITY = serviceframework

    90     

    91     HEADERS += ./inc/ .h

    92     SOURCES += ./src/ .cpp

    93   

    94     DESTDIR = $${EPOCROOT}epoc32/data/c/private/20022F35/import/widgetregistry/20022F7E

    95     

    96     INCLUDEPATH += ./inc               

    97     

    98     symbian: {

    99         INCLUDEPATH += $$APP_LAYER_SYSTEMINCLUDE

   100     

   101         TARGET.UID3 = 0x20022F7E

   102         TARGET.EPOCALLOWDLLDATA=1

   103         TARGET.CAPABILITY = ALL -TCB

   104         

   105         plugins.path = $${DESTDIR}

   106         plugins.sources = $${TARGET}.dll

   107         

   108         widgetResources.path = $${DESTDIR}

   109         widgetResources.sources += resource/$${TARGET}.xml    

   110         widgetResources.sources += resource/$${TARGET}.manifest

   111         widgetResources.sources += resource/$${TARGET}.png

   112         

   113         DEPLOYMENT += plugins \

   114                       widgetResources

   115     }

   116     

   117     @endcode

   118     

   119     For detailed information on DEPLOYMENT macro, see <a HREF="http://pepper.troll.no/s60prereleases/doc/qmake-variable-reference.html#deployment">here</a>.

   120 */

   121 

   122 /*!

   123     \ingroup group_helloworld_widget

   124     \class HelloWorldWidgetPlugin

   125     \brief Example implementation for home screen widget plugin.

   126 */    

   127     

   128 /*!

   129     Initialize plugin for hello world widget. Contains necessary information about 

   130     the hello world widget that it can be loaded through QT Service Framework.

   131 */

   132 QObject *LocalisedHelloWidgetPlugin::createInstance(const QServiceInterfaceDescriptor &descriptor,

   133                                              QServiceContext *context,

   134                                              QAbstractSecuritySession *session)

   135 {

   136     Q_UNUSED(context);

   137     Q_UNUSED(session);

   138 

   139     if (descriptor.interfaceName() == QLatin1String("com.nokia.symbian.IHomeScreenWidget")) {

   140         return new LocalisedHelloWidget();

   141     } else {

   142         return 0;

   143     }

   144 }

   145 

   146 Q_EXPORT_PLUGIN2(localisedhellowidgetplugin, LocalisedHelloWidgetPlugin)