inc/FShellAppWidgetProvider.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Flora License, Version 1.0 (the License);
   6 // you may not use this file except in compliance with the License.
   7 // You may obtain a copy of the License at
   8 //
   9 //     http://floralicense.org/license/
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an "AS IS" BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16 //
  17
  18 /**
  19  * @file        FShellAppWidgetProvider.h
  20  * @brief       This is the header file for the AppWidgetProvider class.
  21  *
  22  * This header file contains the declarations of the %AppManager class.
  23  */
  24
  25 #ifndef _FSHELL_APPWIDGET_PROVIDER_H_
  26 #define _FSHELL_APPWIDGET_PROVIDER_H_
  27
  28 #include <FBaseObject.h>
  29
  30 namespace Tizen { namespace Shell
  31 {
  32
  33 class AppWidgetFrame;
  34
  35 /**
  36  * @class               AppWidgetProvider
  37  * @brief               This class is the abstract base class for all AppWidget providers.
  38  *
  39  * @since       2.1
  40  *
  41  * The %AppWidgetProvider class is an abstract base class, which represents a AppWidget provider.
  42  */
  43 class _OSP_EXPORT_ AppWidgetProvider
  44         : public Tizen::Base::Object
  45 {
  46 protected:
  47
  48         /**
  49          *      This is the default constructor for this class.
  50          *
  51          * @since       2.1
  52          */
  53         AppWidgetProvider(void);
  54
  55         /**
  56          * This destructor overrides Tizen::Base::Object::~Object().
  57          *
  58          * @since       2.1
  59          */
  60         virtual ~AppWidgetProvider(void);
  61
  62         /**
  63          * Called when the AppWidget provider is created or initialized.
  64          *
  65          * @since       2.1
  66          *
  67          * @param[in]   width           The width of the AppWidget
  68          * @param[in]   height          The height of the AppWidget
  69          * @param[in]   userInfo        User information that is specified when the AppWidget is added
  70          *
  71          * @return      @c true if the method is successful, @n
  72          *              else @c false
  73          *
  74          * @remarks     AppWidgetFrame should be created and set here.
  75          * @see         SetAppWidgetFrame()
  76          *
  77          * The following example demonstrates how to initialize the %AppWidgetProvider instance.
  78          *
  79          * @code
  80          * #include <FShell.h>
  81          *
  82          * using namespace Tizen::Shell;
  83          *
  84          * void MyAppWidgetProvider::OnAppWidgetProviderInitializing(int width, int height, const String& userInfo)
  85          * {
  86          *   AppWidgetFrame* pFrame = new MyAppWidgetProviderFrame();
  87          *   pFrame->Construct(Dimension(width, height));
  88          *   __pLabel = new Label();
  89          *
  90          *   Rectangle bounds = GetBounds();
  91          *   __pLabel->Construct(bounds, L"TIZEN");
  92          *   AddControl(*__pLabel);
  93          *   this->SetAppWidgetFrame(pFrame);
  94          *   pFrame->Show();
  95          *
  96          *   return true;
  97          * }
  98          * @endcode
  99          */
 100         virtual bool OnAppWidgetProviderInitializing(float width, float height, const Tizen::Base::String& userInfo) = 0;
 101
 102         /**
 103          * Called when the AppWidget provider is destroyed or terminated.
 104          *
 105          * @since       2.1
 106          */
 107         virtual void OnAppWidgetProviderTerminating(void) = 0;
 108
 109         /**
 110          * Called when the correspondent AppWidget is removed from AppWidget viewer application. (Home or Lock screen, and so on). @n
 111          * If AppWidget provider state is stored in a persistent storage such as registry or DB, it can be destroyed by implementing this pure virtual function.
 112          *
 113          *
 114          * @since       2.1
 115          *
 116          * @remarks     This method is called after the OnAppWidgetProviderTerminating() method is called.
 117          */
 118         virtual void OnAppWidgetProviderRemoved(void) = 0;
 119
 120         /**
 121          * Called when AppWidget is updated. @n
 122          * AppWidget provider can be updated by implementing this pure virtual function.
 123          *
 124          * @since       2.1
 125          *
 126          * @param[in]   argument                User information to update the AppWidget provider @n
 127          *                                                              This parameter is delivered from AppWidgetProvider::RequestUpdate().
 128          *
 129          * @return      @c true if the method is successful, @n
 130          *              else @c false
 131          *
 132          * @remarks             This method is called when UpdatePeriod timer is expired or AppWidgetManager::RequestUpdate() is called.@n
 133          */
 134         virtual bool OnAppWidgetProviderUpdating(const Tizen::Base::String& argument) = 0;
 135
 136         /**
 137          * Sets the AppWidgetFrame instance to the AppWidgetProvider instance.
 138          *
 139          * @since       2.1
 140          *
 141          * @return      An error code
 142          * @param[in]   pAppWidgetFrame         The AppWidgetFrame instance to set as the AppWidgetProvider instance
 143          * @exception   E_SUCCESS           The method is successful.
 144          * @exception   E_INVALID_ARG           The pointer to AppWidgetFrame is @c null, or not constructed as yet.
 145          * @exception   E_SYSTEM            The method cannot proceed due to a severe system error.
 146          *
 147          * @remarks             This method should be called only within the OnAppWidgetProviderInitializing() method.
 148          * @remarks             The AppWidgetFrame instance ownership is transferred to the platform. After AppWidgetProvider::OnAppWidgetProviderTerminating() is called, the AppWidgetPopup instance is removed automatically. The %AppWidgetFrame instance reuse is not allowed.
 149          */
 150         result SetAppWidgetFrame(AppWidgetFrame* pAppWidgetFrame);
 151
 152         /**
 153          * Gets the AppWidgetFrame instance from the AppWidgetProvider instance.
 154          *
 155          * @since       2.1
 156          *
 157          * @return      The AppWidgetFrame instance, or @c null if any %AppWidgetFrame is not set yet
 158          */
 159         AppWidgetFrame* GetAppWidgetFrame(void);
 160
 161         /**
 162          * Gets the AppWidgetFrame instance from the AppWidgetProvider instance.
 163          *
 164          * @since       2.1
 165          *
 166          * @return      The AppWidgetFrame instance, or @c null if any %AppWidgetFrame is not set yet
 167          */
 168         const AppWidgetFrame* GetAppWidgetFrame(void) const;
 169
 170 protected:
 171         //
 172         // This method is for internal use only. Using this method can cause behavioral,
 173         // security-related, and consistency-related issues in the application.
 174         //
 175         // @since       2.1
 176         //
 177         virtual void AppWidgetProvider_Reserved1(void) {}
 178
 179         //
 180         // This method is for internal use only. Using this method can cause behavioral,
 181         // security-related, and consistency-related issues in the application.
 182         //
 183         // @since       2.1
 184         //
 185         virtual void AppWidgetProvider_Reserved2(void) {}
 186
 187         //
 188         // This method is for internal use only. Using this method can cause behavioral,
 189         // security-related, and consistency-related issues in the application.
 190         //
 191         // @since       2.1
 192         //
 193         virtual void AppWidgetProvider_Reserved3(void) {}
 194
 195         //
 196         // This method is for internal use only. Using this method can cause behavioral,
 197         // security-related, and consistency-related issues in the application.
 198         //
 199         // @since       2.1
 200         //
 201         virtual void AppWidgetProvider_Reserved4(void) {}
 202
 203         //
 204         // This method is for internal use only. Using this method can cause behavioral,
 205         // security-related, and consistency-related issues in the application.
 206         //
 207         // @since       2.1
 208         //
 209         virtual void AppWidgetProvider_Reserved5(void) {}
 210
 211 private:
 212
 213         //
 214         // Initializes this instance of %AppWidgetProvider
 215         //
 216         // @since       2.1
 217         //
 218         result Construct(const Tizen::Base::String& instanceId);
 219
 220         //
 221         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 222         //
 223         // @since       2.1
 224         //
 225         AppWidgetProvider(const AppWidgetProvider& rhs);
 226
 227         //
 228         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 229         //
 230         // @since       2.1
 231         //
 232         AppWidgetProvider& operator =(const AppWidgetProvider& rhs);
 233
 234
 235 private:
 236         class _AppWidgetProviderImpl* __pAppWidgetProviderImpl;
 237
 238         friend class _AppWidgetProviderManagerImpl;
 239 };
 240
 241 }} // Tizen::Shell
 242 #endif /* _FSHELL_APPWIDGET_PROVIDER_H_ */