2 // Open Service Platform
3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
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
9 // http://floralicense.org/license/
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.
19 * @file FShellAppWidgetProvider.h
20 * @brief This is the header file for the AppWidgetProvider class.
22 * This header file contains the declarations of the %AppManager class.
25 #ifndef _FSHELL_APPWIDGET_PROVIDER_H_
26 #define _FSHELL_APPWIDGET_PROVIDER_H_
28 #include <FBaseObject.h>
30 namespace Tizen { namespace Shell
36 * @class AppWidgetProvider
37 * @brief This class is the abstract base class for all AppWidget providers.
41 * The %AppWidgetProvider class is an abstract base class, which represents a AppWidget provider.
43 class _OSP_EXPORT_ AppWidgetProvider
44 : public Tizen::Base::Object
49 * This is the default constructor for this class.
53 AppWidgetProvider(void);
56 * This destructor overrides Tizen::Base::Object::~Object().
60 virtual ~AppWidgetProvider(void);
63 * Called when the AppWidget provider is created or initialized.
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
71 * @return @c true if the method is successful, @n
74 * @remarks AppWidgetFrame should be created and set here.
75 * @see SetAppWidgetFrame()
77 * The following example demonstrates how to initialize the %AppWidgetProvider instance.
82 * using namespace Tizen::Shell;
84 * void MyAppWidgetProvider::OnAppWidgetProviderInitializing(int width, int height, const String& userInfo)
86 * AppWidgetFrame* pFrame = new MyAppWidgetProviderFrame();
87 * pFrame->Construct(Dimension(width, height));
88 * __pLabel = new Label();
90 * Rectangle bounds = GetBounds();
91 * __pLabel->Construct(bounds, L"TIZEN");
92 * AddControl(*__pLabel);
93 * this->SetAppWidgetFrame(pFrame);
100 virtual bool OnAppWidgetProviderInitializing(float width, float height, const Tizen::Base::String& userInfo) = 0;
103 * Called when the AppWidget provider is destroyed or terminated.
107 virtual void OnAppWidgetProviderTerminating(void) = 0;
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.
116 * @remarks This method is called after the OnAppWidgetProviderTerminating() method is called.
118 virtual void OnAppWidgetProviderRemoved(void) = 0;
121 * Called when AppWidget is updated. @n
122 * AppWidget provider can be updated by implementing this pure virtual function.
126 * @param[in] userInfo User information to update the AppWidget provider @n
127 * This parameter is delivered from AppWidgetProvider::RequestUpdate().
129 * @return @c true if the method is successful, @n
132 * @remarks This method is called when UpdatePeriod timer is expired or AppWidgetManager::RequestUpdate() is called.@n
134 virtual bool OnAppWidgetProviderUpdating(const Tizen::Base::String& argument) = 0;
137 * Sets the AppWidgetFrame instance to the AppWidgetProvider instance.
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.
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.
150 result SetAppWidgetFrame(AppWidgetFrame* pAppWidgetFrame);
153 * Gets the AppWidgetFrame instance from the AppWidgetProvider instance.
157 * @return The AppWidgetFrame instance, or @c null if any %AppWidgetFrame is not set yet
159 AppWidgetFrame* GetAppWidgetFrame(void);
162 * Gets the AppWidgetFrame instance from the AppWidgetProvider instance.
166 * @return The AppWidgetFrame instance, or @c null if any %AppWidgetFrame is not set yet
168 const AppWidgetFrame* GetAppWidgetFrame(void) const;
172 // This method is for internal use only. Using this method can cause behavioral,
173 // security-related, and consistency-related issues in the application.
177 virtual void AppWidgetProvider_Reserved1(void) {}
180 // This method is for internal use only. Using this method can cause behavioral,
181 // security-related, and consistency-related issues in the application.
185 virtual void AppWidgetProvider_Reserved2(void) {}
188 // This method is for internal use only. Using this method can cause behavioral,
189 // security-related, and consistency-related issues in the application.
193 virtual void AppWidgetProvider_Reserved3(void) {}
196 // This method is for internal use only. Using this method can cause behavioral,
197 // security-related, and consistency-related issues in the application.
201 virtual void AppWidgetProvider_Reserved4(void) {}
204 // This method is for internal use only. Using this method can cause behavioral,
205 // security-related, and consistency-related issues in the application.
209 virtual void AppWidgetProvider_Reserved5(void) {}
214 // Initializes this instance of %AppWidgetProvider
218 result Construct(const Tizen::Base::String& instanceId);
221 // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
225 AppWidgetProvider(const AppWidgetProvider& rhs);
228 // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
232 AppWidgetProvider& operator =(const AppWidgetProvider& rhs);
236 class _AppWidgetProviderImpl* __pAppWidgetProviderImpl;
238 friend class _AppWidgetProviderManagerImpl;
242 #endif /* _FSHELL_APPWIDGET_PROVIDER_H_ */