inc/FUiClipboard.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012-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        FUiClipboard.h
  20  * @brief       This is the header file for the %Clipboard class.
  21  *
  22  * This header file contains the declarations of the %Clipboard class and its helper classes.
  23  */
  24
  25 #ifndef _FUI_CLIPBOARD_H_
  26 #define _FUI_CLIPBOARD_H_
  27
  28 #include <FBaseObject.h>
  29 #include <FBaseTypes.h>
  30 #include <FBaseString.h>
  31 #include <FBaseColIList.h>
  32 #include <FUiClipboardItem.h>
  33 #include <FUiIClipboard.h>
  34 #include <FUiIClipboardPopupEventListener.h>
  35
  36 namespace Tizen { namespace Ui
  37 {
  38 class _ClipboardImpl;
  39
  40 /**
  41  * @class       Clipboard
  42  * @brief       This class defines a common behavior for %Clipboard.
  43  *
  44  * @since       2.0
  45  *
  46  * @final       This class is not intended for extension.
  47  *
  48  * The %Clipboard class manages the copy and paste operation between and within applications.
  49  *
  50  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/clipboard.htm">Clipboard</a>.
  51  *
  52  * The following example demonstrates how to use the %Clipboard class.
  53  *
  54  * @code
  55 // Sample code for ClipboardSample.h
  56 #include <FUi.h>
  57
  58 class ClipboardSample
  59         : public Tizen::Ui::Controls::Form
  60         , public Tizen::Ui::IActionEventListener
  61 {
  62 public:
  63         ClipboardSample(void)
  64         : __pLabel(null){}
  65
  66         bool Initialize(void);
  67         virtual result OnInitializing(void);
  68
  69         // IActionEventListener
  70         virtual void OnActionPerformed(const Tizen::Ui::Control& source, int actionId);
  71
  72 private:
  73         static const int ID_BUTTON_OK = 101;
  74
  75         Tizen::Ui::Controls::Label* __pLabel;
  76 };
  77  * @endcode
  78  *
  79  * @code
  80 // Sample code for ClipboardSample.cpp
  81 #include <FApp.h>
  82 #include <FBase.h>
  83 #include <FGraphics.h>
  84
  85 #include "ClipboardSample.h"
  86
  87 using namespace Tizen::App;
  88 using namespace Tizen::Base;
  89 using namespace Tizen::Graphics;
  90 using namespace Tizen::Ui;
  91 using namespace Tizen::Ui::Controls;
  92
  93 bool
  94 ClipboardSample::Initialize(void)
  95 {
  96         Construct(FORM_STYLE_NORMAL);
  97         return true;
  98 }
  99
 100 result
 101 ClipboardSample::OnInitializing(void)
 102 {
 103         result r = E_SUCCESS;
 104
 105         // Sets data to a clip board item
 106         ClipboardItem item;
 107         String resourcePath = App::GetInstance()->GetAppResourcePath();
 108         item.Construct(CLIPBOARD_DATA_TYPE_HTML, String(resourcePath + L"screen-size-normal/IDF_FORM.xml"));
 109
 110         // Gets an instance of Clipboard and copies an item to it
 111         Clipboard* pClipboard = Clipboard::GetInstance();
 112         pClipboard->CopyItem(item);
 113
 114         // Creates controls to test clipboard
 115         Button* pButton = new Button();
 116         pButton->Construct(Rectangle(50, 50, 200, 80), "COPY");
 117         pButton->SetActionId(ID_BUTTON_OK);
 118         pButton->AddActionEventListener(*this);
 119         AddControl(*pButton);
 120
 121         __pLabel = new Label();
 122         __pLabel->Construct(Rectangle(0, 200, GetClientAreaBounds().width, 80), L"..");
 123         AddControl(*__pLabel);
 124
 125         return r;
 126 }
 127
 128 void
 129 ClipboardSample::OnActionPerformed(const Tizen::Ui::Control& source, int actionId)
 130 {
 131         switch(actionId)
 132         {
 133         case ID_BUTTON_OK:
 134                 {
 135                         // Gets an instance of Clipboard
 136                         Clipboard* pClipboard = Clipboard::GetInstance();
 137
 138                         // Retrieves a latest item
 139                         ClipboardItem* pItem = pClipboard->RetrieveLatestItemN(CLIPBOARD_DATA_TYPE_TEXT
 140                                         | CLIPBOARD_DATA_TYPE_HTML
 141                                         | CLIPBOARD_DATA_TYPE_AUDIO
 142                                         | CLIPBOARD_DATA_TYPE_VIDEO );
 143
 144                         //Gets data from the clipboard item
 145                         String* pString = dynamic_cast<String*>(pItem->GetData());
 146
 147                         __pLabel->SetText(*pString + L" is Copied");
 148                         __pLabel->Invalidate(false);
 149
 150                         delete pItem;
 151                 }
 152                 break;
 153         default:
 154                 break;
 155         }
 156 }
 157  * @endcode
 158  */
 159 class _OSP_EXPORT_ Clipboard
 160         : public Tizen::Base::Object
 161         , public Tizen::Ui::IClipboard
 162 {
 163 public:
 164         /**
 165          * Gets the system clipboard.
 166          *
 167          * @since   2.0
 168          *
 169          * @return  The pointer to the system clipboard
 170          * @remarks The copy and paste operation is performed through the system
 171          *          clipboard that can be obtained through this method. @n
 172          *          The method returns @c null if a system error occurs.
 173          */
 174         static Clipboard* GetInstance(void);
 175
 176         /**
 177          * Copies the specified @c item to the system clipboard.
 178          *
 179          * @since       2.0
 180          *
 181          * @return      An error code
 182          * @param[in]   item            The item to save in the system clipboard
 183          * @exception   E_SUCCESS       The method is successful.
 184          * @exception   E_INVALID_ARG   The specified input parameter is invalid.
 185          * @exception   E_SYSTEM        A system error has occurred.
 186          * @remarks     This method returns @c E_INVALID_ARG if the specified item is
 187          *              not constructed. @n
 188          *              For the text and image data type, the data itself is copied
 189          *              by the method and kept by the system clipboard.
 190          */
 191         result CopyItem(const ClipboardItem& item);
 192
 193         /**
 194          * Retrieves a collection of items that matches the specified data types from the
 195          * system clipboard.
 196          *
 197          * @since       2.0
 198          *
 199          * @return      The pointer to a Tizen::Base::Collection::IList that contains a collection of ClipboardItem, @n
 200          *              else @c null if an error occurs
 201          * @param[in]   dataTypes       The types of items @n Multiple data types can be
 202          *                              combined using bitwise OR.
 203          * @exception   E_SUCCESS       The method is successful.
 204          * @exception   E_OBJ_NOT_FOUND The item of the specified data types is not found.
 205          * @exception   E_SYSTEM        A system error has occurred.
 206          * @remarks     The specific error code can be accessed using the GetLastResult() method. @n
 207          *              This method returns a pointer to an Tizen::Base::Collection::IList that contains
 208          *              a collection of ClipboardItem. The returned pointer to %Tizen::Base::Collection::IList
 209          *              and all the elements in %Tizen::Base::Collection::IList must be deleted by applications. @n
 210          *              The items in %Tizen::Base::Collection::IList are sorted in the reverse order in which
 211          *              they are copied to the system clipboard. So, the first
 212          *              item in %Tizen::Base::Collection::IList is the latest one among them. @n
 213          *              @c dataType can be a combination of ClipboardDataType.
 214          * @see Tizen::Ui::ClipboardDataType
 215          */
 216         Tizen::Base::Collection::IList* RetrieveItemsN(unsigned long dataTypes);
 217
 218         /**
 219          * Retrieves the latest item for the specified data types from the system clipboard.
 220          *
 221          * @since       2.0
 222          *
 223          * @return      The pointer to a ClipboardItem instance, @n
 224          *              else @c null if an error occurs
 225          * @param[in]   dataTypes       The types of items @n Multiple data types can be
 226          *                              combined using bitwise OR.
 227          * @exception   E_SUCCESS       The method is successful.
 228          * @exception   E_OBJ_NOT_FOUND The item of the specified data types is not found.
 229          * @exception   E_SYSTEM        A system error has occurred.
 230          * @remarks     The specific error code can be accessed using the GetLastResult() method. @n
 231          *              This method returns the pointer to a ClipboardItem instance. The
 232          *              returned %ClipboardItem must be deleted by applications. @n
 233          *              If there is no matched item in the system clipboard, this method
 234          *              returns @c null. @n
 235          *              @c dataType can be a combination of ClipboardDataType.
 236          * @see Tizen::Ui::ClipboardDataType
 237          */
 238         Tizen::Ui::ClipboardItem* RetrieveLatestItemN(unsigned long dataTypes);
 239
 240         /**
 241          * Shows the clipboard popup with the specified parameters.
 242          *
 243          * @since     2.0
 244          *
 245          * @return        An error code
 246          * @param[in] dataTypes           The types of items @n Multiple data types can be
 247          *                                combined using bitwise OR.
 248          * @param[in] listener            The clipboard popup event listener
 249          * @exception E_SUCCESS           The method is successful.
 250          * @exception E_INVALID_OPERATION The current state of the instance
 251          *                                prohibits the execution of the specified
 252          *                                operation.
 253          * @exception E_SYSTEM            A system error has occurred.
 254          * @remarks    @c dataTypes can decide whether the clipboard popup shows image items or not.
 255          *            If @c dataTypes contains #CLIPBOARD_DATA_TYPE_IMAGE, all types of items are shown.
 256          *            If not, text items, html items, video items, and audio items are shown except image items. @n
 257          *            This method returns @c E_INVALID_OPERATION if the clipboard popup is currently
 258          *            being shown. Furthermore, attempting to show the clipboard popup when the application is
 259          *            in the background will return @c E_INVALID_OPERATION. @n
 260          *            The clipboard popup shows the current content of the system clipboard. The user
 261          *            can clear the system clipboard or choose a clipboard item for the paste operation.
 262          * @see Tizen::Ui::ClipboardDataType
 263          */
 264         static result ShowPopup(unsigned long dataTypes, const IClipboardPopupEventListener& listener);
 265
 266         /**
 267          * Hides the clipboard popup.
 268          *
 269          * @since          2.0
 270          *
 271          * @return         An error code
 272          * @exception      E_SUCCESS             The method is successful.
 273          * @exception      E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation.
 274          * @exception      E_SYSTEM              A system error has occurred.
 275          * @remarks        This method returns @c E_INVALID_OPERATION if no clipboard popup is currently being shown.
 276          */
 277         static result HidePopup(void);
 278
 279         /**
 280          * Checks whether the clipboard popup is currently being shown.
 281          *
 282          * @since          2.0
 283          *
 284          * @return         @c true if the clipboard popup is being shown, @n
 285          *                 else @c false
 286          */
 287         static bool IsPopupVisible(void);
 288
 289 private:
 290         //
 291         // This default constructor is intentionally declared as private to implement the Singleton semantic.
 292         //
 293         Clipboard(void);
 294
 295         //
 296         // This destructor is intentionally declared as private to implement the Singleton semantic.
 297         //
 298         virtual ~Clipboard(void);
 299
 300         //
 301         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 302         //
 303         Clipboard(const Clipboard& rhs);
 304
 305         //
 306         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 307         //
 308         Clipboard& operator =(const Clipboard& rhs);
 309
 310 private:
 311         friend class _ClipboardImpl;
 312
 313 private:
 314         _ClipboardImpl* __pClipboardImpl;
 315 }; // Clipboard
 316
 317 }} //Tizen::Ui
 318
 319 #endif //_FUI_CLIPBOARD_H_