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, @n
 170          *                      else @c null if a system error has occurred
 171          * @remarks     The copy and paste operation is performed through the system clipboard.
 172          */
 173         static Clipboard* GetInstance(void);
 174
 175         /**
 176          * Copies the specified @c item to the system clipboard.
 177          *
 178          * @since       2.0
 179          *
 180          * @return      An error code
 181          * @param[in]   item            The item to save in the system clipboard
 182          * @exception   E_SUCCESS       The method is successful.
 183          * @exception   E_INVALID_ARG   The specified input parameter is either invalid or not constructed.
 184          * @exception   E_SYSTEM        A system error has occurred.
 185          * @remarks     For the text, image data, and html types, the data itself is copied by the method and kept by the system clipboard. @n
 186          *                      For the other types, only the file path is copied and kept.
 187          */
 188         result CopyItem(const ClipboardItem& item);
 189
 190         /**
 191          * Retrieves a collection of items that matches the specified data types from the
 192          * system clipboard.
 193          *
 194          * @since               2.0
 195          *
 196          * @return      The pointer to a Tizen::Base::Collection::IList that contains a collection of ClipboardItem, @n
 197          *                      else @c null if an error has occurred @n
 198          *                      The items are sorted in the reverse order in which they are copied to the system clipboard. So, the first item is the latest one among them.
 199          * @param[in]   dataTypes       The types of items @n
 200          *                      Multiple data types of ClipboardDataType can be combined using bitwise OR.
 201          * @exception   E_SUCCESS       The method is successful.
 202          * @exception   E_OBJ_NOT_FOUND The item of the specified data types is not found.
 203          * @exception   E_SYSTEM        A system error has occurred.
 204          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 205          */
 206         Tizen::Base::Collection::IList* RetrieveItemsN(unsigned long dataTypes);
 207
 208         /**
 209          * Retrieves the latest item for the specified data types from the system clipboard.
 210          *
 211          * @since       2.0
 212          *
 213          * @return      The pointer to a ClipboardItem instance, @n
 214          *              else @c null if an error has occurred or there is no matched item in the system clipboard
 215          * @param[in]   dataTypes       The types of items @n Multiple data types of ClipboardDataType can be
 216          *                              combined using bitwise OR.
 217          * @exception   E_SUCCESS       The method is successful.
 218          * @exception   E_OBJ_NOT_FOUND The item of the specified data types is not found.
 219          * @exception   E_SYSTEM        A system error has occurred.
 220          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 221          */
 222         Tizen::Ui::ClipboardItem* RetrieveLatestItemN(unsigned long dataTypes);
 223
 224         /**
 225          * Shows the clipboard popup that is including the current contents of the system clipboard with the specified parameters.
 226          *
 227          * @since     2.0
 228          *
 229          * @return        An error code
 230          * @param[in] dataTypes           The types of items to decide whether the clipboard popup shows image items or not @n
 231          *                                              Multiple data types of ClipboardDataType can be combined using bitwise OR. @n
 232          *                                              If the value contains #CLIPBOARD_DATA_TYPE_IMAGE, all types of items are shown. @n
 233          *                                              If not, text items, html items, video items, and audio items are shown except image items.
 234          * @param[in] listener            The clipboard popup event listener
 235          * @exception E_SUCCESS           The method is successful.
 236          * @exception E_INVALID_OPERATION       Either the clipboard popup is currently being shown or attempting to show the clipboard popup
 237          *                                                              when the application is in the background.
 238          * @exception E_SYSTEM            A system error has occurred.
 239          * @remarks    The user can operate the system clipboard when the clipboard popup is shown,
 240          *                      for example, clear the system clipboard or choose a clipboard item for the paste operation.
 241          */
 242         static result ShowPopup(unsigned long dataTypes, const IClipboardPopupEventListener& listener);
 243
 244         /**
 245          * Hides the clipboard popup.
 246          *
 247          * @since          2.0
 248          *
 249          * @return         An error code
 250          * @exception      E_SUCCESS             The method is successful.
 251          * @exception      E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation.
 252          *                                                              - No clipboard popup is currently being shown.
 253          * @exception      E_SYSTEM              A system error has occurred.
 254          */
 255         static result HidePopup(void);
 256
 257         /**
 258          * Checks whether the clipboard popup is currently being shown.
 259          *
 260          * @since          2.0
 261          *
 262          * @return         @c true if the clipboard popup is being shown, @n
 263          *                 else @c false
 264          */
 265         static bool IsPopupVisible(void);
 266
 267 private:
 268         //
 269         // This default constructor is intentionally declared as private to implement the Singleton semantic.
 270         //
 271         Clipboard(void);
 272
 273         //
 274         // This destructor is intentionally declared as private to implement the Singleton semantic.
 275         //
 276         virtual ~Clipboard(void);
 277
 278         //
 279         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 280         //
 281         Clipboard(const Clipboard& rhs);
 282
 283         //
 284         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 285         //
 286         Clipboard& operator =(const Clipboard& rhs);
 287
 288 private:
 289         friend class _ClipboardImpl;
 290
 291 private:
 292         _ClipboardImpl* __pClipboardImpl;
 293 }; // Clipboard
 294
 295 }} //Tizen::Ui
 296
 297 #endif //_FUI_CLIPBOARD_H_