inc/FShellShortcutManager.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2013 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Apache License, Version 2.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://www.apache.org/licenses/LICENSE-2.0
  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     FShellShortcutManager.h
  20  * @brief    This is the header file for the %ShortcutManager class.
  21  *
  22  * This header file contains the declarations of the %ShortcutManager class.
  23  */
  24
  25 #ifndef _FSHELL_SHORTCUT_MANAGER_H_
  26 #define _FSHELL_SHORTCUT_MANAGER_H_
  27
  28 #include <FBaseObject.h>
  29 #include <FBaseString.h>
  30 #include <FAppTypes.h>
  31
  32
  33 namespace Tizen { namespace Shell
  34 {
  35
  36 class IShortcutRequestListener;
  37
  38 /**
  39  * @class               ShortcutManager
  40  * @brief               This class helps an application to add its shortcut to the Home app.
  41  *
  42  * @since       2.1
  43  *
  44  * @final               This class is not intended for extension.
  45  *
  46  * The %ShortcutManager class helps an application to add its shortcut to the Home app.
  47  */
  48 class _OSP_EXPORT_ ShortcutManager
  49         : public Tizen::Base::Object
  50 {
  51 public:
  52
  53         /**
  54          * Gets the %ShortcutManager instance.
  55          *
  56          * @since       2.1
  57          *
  58          * @return      A pointer to the %ShortcutManager instance, @n
  59          *                      else @c null if it fails
  60          * @exception      E_SUCCESS       The method is successful.
  61          * @exception      E_OUT_OF_MEMORY                    The memory is insufficient.
  62          * @exception      E_SYSTEM                                   The method cannot proceed due to a severe system error.
  63          * @remarks        The specific error code can be accessed using the GetLastResult() method.
  64          */
  65         static ShortcutManager* GetInstance(void);
  66
  67         /**
  68          * Adds a shortcut to Home app.
  69          *
  70          * @since       2.1
  71          * @privlevel   public
  72          * @privilege   %http::tizen.org/privilege/shortcut.install
  73          *
  74          * @return      An error code
  75          * @param[in]   appId   The application ID
  76          * @param[in]   displayName     The display name of shortcut
  77          * @param[in]   iconPath        The icon file path
  78          * @param[in]   uriData                         Uri that will be delivered by Tizen::App::IAppControlProviderEventListener::OnAppControlRequestReceived(), when the application is started using a shortcut.
  79          * @param[in]   allowDuplication        Flag to allow duplicate shortcut
  80          *
  81          * @exception   E_SUCCESS                       The method is successful.
  82          * @exception   E_APP_NOT_INSTALLED     The application is not installed.
  83          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
  84          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
  85          *
  86          * @remarks
  87          *                              - Icon file should be placed in sub directory of 'shared/res' to be used by the Home app.
  88          *                              For more information on shared directory, see <a href="../org.tizen.native.appprogramming/html/basics_tizen_programming/io_overview.htm">I/O Overview</a>
  89          *                              and see <a href="../org.tizen.native.appprogramming/html/app_dev_process/manifest_general.htm">General Information</a> for icon file.
  90          *                              - If @c uriData is specified, application will be started by AppControl with %http://tizen.org/appcontrol/operation/view operation, when it is launched from the Home app using a shortcut.
  91          *                              Or else application will be started by AppControl with default operation(%http://tizen.org/appcontrol/operation/main).
  92          *
  93          * @see                 Tizen::App::IAppControlEventListener::OnAppControlRequestReceived()
  94          * @see                 IShortcutRequestListener::OnShortcutAddRequested()
  95          *
  96          * The following example demonstrates how to add shortcut.
  97          *
  98          * @code
  99          * #include <FApp.h>
 100          * #include <FShell.h>
 101          *
 102          * using namespace Tizen::App;
 103          * using namespace Tizen::Shell;
 104          *
 105          * String displayName = L"Shortcut to my app";
 106          * String iconPath = App::GetInstance()->GetAppSharedPath() + L"res/screen-density-xhigh/mainmenu.png";
 107          * String uriData = L"myapp://mydata/myitem";
 108          * ShortcutManager::GetInstance()->AddShortcut(App::GetInstance()->GetAppId(), displayName, iconPath , uriData);
 109          * @endcode
 110          */
 111         result AddShortcut(const Tizen::App::AppId& appId, const Tizen::Base::String& displayName, const Tizen::Base::String& iconPath, const Tizen::Base::String& uriData, bool allowDuplication = true );
 112
 113         /**
 114          * Removes a shortcut from Home app.
 115          *
 116          * @since       2.1
 117          * @privlevel   public
 118          * @privilege   %http://tizen.org/privilege/shortcut
 119          *
 120          * @return      An error code
 121          * @param[in]   appId   The application ID
 122          * @param[in]   displayName     The display name of shortcut
 123          * @exception   E_SUCCESS                       The method is successful.
 124          * @exception   E_APP_NOT_INSTALLED     The application is not installed.
 125          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 126          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 127          * @remarks     If there are more than one shortcuts with duplicated @c appId and @c displayName in the Home app, all of them will be removed.
 128          *
 129          * @see                 IShortcutRequestListener::OnShortcutRemoveRequested()
 130          */
 131         result RemoveShortcut(const Tizen::App::AppId& appId, const Tizen::Base::String& displayName);
 132
 133         /**
 134          * Adds an IShortcutRequestListener to the %ShortcutManager. @n
 135          * The listener gets notified when requested to add a shortcut.
 136          *
 137          * @since       2.1
 138          *
 139          * @return              An error code
 140          * @param[in]   listener                                The event listener to add
 141          * @exception   E_SUCCESS                               The method is successful.
 142          * @exception   E_OBJ_ALREADY_EXIST             The listener is already added.
 143          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.
 144          */
 145         result AddShortcutRequestListener(IShortcutRequestListener& listener);
 146
 147         /**
 148          * Removes an IShortcutRequestListener from the %ShortcutManager.
 149          *
 150          * @since       2.1
 151          *
 152          * @return              An error code
 153          * @param[in]   listener                        The event listener to remove
 154          * @exception   E_SUCCESS                       The method is successful.
 155          * @exception   E_OBJ_NOT_FOUND         The listener is not found.
 156          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 157          */
 158         result RemoveShortcutRequestListener(IShortcutRequestListener& listener);
 159
 160 private:
 161         //
 162         // This default constructor is intentionally declared as private to implement the %Singleton semantic.
 163         //
 164         // @since       2.1
 165         //
 166         ShortcutManager(void);
 167
 168         //
 169         // This destructor is intentionally declared as private to implement the %Singleton semantic.
 170         //
 171         // @since       2.1
 172         //
 173         virtual ~ShortcutManager(void);
 174
 175         //
 176         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 177         //
 178         // @since       2.1
 179         //
 180         ShortcutManager& operator =(const ShortcutManager& rhs);
 181
 182         //
 183         // Constructs the instance of this class.
 184         //
 185         // @since       2.1
 186         //
 187         // @return          An error code
 188         // @exception   E_SUCCESS       The method is successful.
 189         // @exception   E_SYSTEM        The method cannot proceed due to a severe system error.
 190         //
 191         result Construct(void);
 192
 193         static void InitSingleton(void);
 194         static void DestroySingleton(void);
 195
 196 private:
 197         static ShortcutManager* __pTheInstance;
 198         friend struct std::default_delete< ShortcutManager >;
 199         class _ShortcutManagerImpl* __pShortcutManagerImpl;
 200 };
 201
 202 }} // Tizen::Shell
 203 #endif /* _FSHELL_SHORTCUT_MANAGER_H_ */