inc/FUiEffectsEffect.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 * @file        FUiEffectsEffect.h
  19 * @brief       This is the header file for the %Effect class.
  20 *
  21 * This header file contains the declarations of the %Effect class.
  22 */
  23
  24 #ifndef _FUI_EFFECTS_EFFECT_H_
  25 #define _FUI_EFFECTS_EFFECT_H_
  26
  27 #include <FBaseObject.h>
  28 #include <FUiEffectsTypes.h>
  29
  30
  31 namespace Tizen { namespace Base {
  32 class String;
  33 }} // Tizen::Base
  34
  35 namespace Tizen { namespace Ui {
  36 class TouchEventInfo;
  37 class Control;
  38 }} // Tizen::Ui
  39
  40 namespace Tizen { namespace Graphics {
  41 class Bitmap;
  42 class Point;
  43 }} // Tizen::Graphics
  44
  45 namespace Tizen { namespace Base { namespace Collection {
  46 class IList;
  47 }}} // Tizen::Base::Collection
  48
  49 namespace Tizen { namespace Ui { namespace Effects
  50 {
  51 class IEffectEventListener;
  52 class IEffectResourceProvider;
  53 class _EffectImpl;
  54
  55 /**
  56 * @class      Effect
  57 * @brief      This class contains API for managing effects.
  58 *
  59 * @since 2.0
  60 *
  61 * The %Effect class contains API for managing effects.
  62 */
  63 class _OSP_EXPORT_ Effect
  64         : public Tizen::Base::Object
  65 {
  66 public:
  67         /**
  68          * Binds the effect to Tizen::UI::Control for rendering effect.
  69          *
  70          * @since 2.0
  71          *
  72          * @return        An error code
  73          * @param [in] pControl          Tizen::UI::Control whose content is filled by the effect
  74          * @exception  E_SUCCESS         The specified effect is bound with @c control successfully.
  75          * @exception   E_OPERATION_FAILED      The system has failed to initialize the 3D system.
  76          * @exception   E_IN_PROGRESS           The specified effect is running now, setting, changing or resetting render target is impossible
  77          */
  78         result SetRenderTarget(Tizen::Ui::Control* pControl);
  79
  80         /**
  81          * Starts the effect.
  82          *
  83          * @since 2.0
  84          *
  85          * @return        An error code
  86          * @exception  E_SUCCESS                  The specified effect is started successfully.
  87          * @exception  E_INVALID_STATE    The specified effect has already started.
  88          * @exception  E_OPERATION_FAILED The specified effect has a runtime error in the script.
  89          * @exception  E_ALREADY_SET      Other effects which use the same control as a render target are currently running.
  90          */
  91         result Start(void);
  92
  93         /**
  94          * Starts the effect.
  95          *
  96          * @since 2.0
  97          *
  98          * @return        An error code
  99          * @param [in] effectStartInfo    A list of input arguments to pass to the OnEffectStarted() method of the scripts @n
 100          *                                                                All arguments must be represented in @c float data type.
 101          * @exception  E_SUCCESS                  The specified effect is started successfully.
 102          * @exception  E_INVALID_STATE    The specified effect has already started.
 103          * @exception  E_OPERATION_FAILED The specified effect has a runtime error in the script.
 104          * @exception  E_ALREADY_SET      Other effects which use the same control as a render target are currently running.
 105          */
 106         result Start(const Tizen::Base::Collection::IList& effectStartInfo);
 107
 108         /**
 109          * Stops the effect.
 110          *
 111          * @since 2.0
 112          *
 113          * @return        An error code
 114          * @exception  E_SUCCESS           The specified effect is stopped successfully.
 115          * @exception  E_INVALID_STATE The specified effect has not started as yet.
 116          */
 117         result Stop(void);
 118
 119         /**
 120          * Informs the effect of a TouchPress event.
 121          *
 122          * @since 2.0
 123          *
 124          * @return        An error code
 125          * @param [in] touchEventInfo     The touch event information
 126          * @param [in] offset                     The effect will regard the touch position in @c touchEventInfo translated by @c offset
 127          * @exception  E_SUCCESS                  The specified effect is successfully sent with a TouchPress event.
 128          * @exception  E_INVALID_STATE    The specified effect has not started as yet.
 129          * @exception  E_OPERATION_FAILED There is a runtime error in the OnTouchPressed() script method or the effect is time-based.
 130          */
 131         result FeedTouchPressEvent(const Tizen::Ui::TouchEventInfo& touchEventInfo, const Tizen::Graphics::Point& offset);
 132
 133         /**
 134          * Informs the effect of a TouchPress event.
 135          *
 136          * @since 2.0
 137          *
 138          * @return        An error code
 139          * @param [in] touchEventInfo     The touch event information
 140          * @exception  E_SUCCESS                  The specified effect is successfully sent with a TouchPress event.
 141          * @exception  E_INVALID_STATE    The specified effect has not started as yet.
 142          * @exception  E_OPERATION_FAILED There is a runtime error in the OnTouchPressed() script method or the effect is time-based.
 143          */
 144         result FeedTouchPressEvent(const Tizen::Ui::TouchEventInfo& touchEventInfo);
 145
 146         /**
 147          * Informs the effect of a TouchMove event.
 148          *
 149          * @since 2.0
 150          *
 151          * @return        An error code
 152          * @param [in] touchEventInfo     The touch event information
 153          * @param [in] offset                     The effect will regard the touch position in @c touchEventInfo translated by @c offset
 154          * @exception  E_SUCCESS                  The specified effect is successfully sent with a TouchMove event.
 155          * @exception  E_INVALID_STATE    The specified effect has not started as yet.
 156          * @exception  E_OPERATION_FAILED There is a runtime error in the OnTouchMoved() script method or the effect is time-based.
 157          */
 158         result FeedTouchMoveEvent(const Tizen::Ui::TouchEventInfo& touchEventInfo, const Tizen::Graphics::Point& offset);
 159
 160         /**
 161          * Informs the effect of a TouchMove event.
 162          *
 163          * @since 2.0
 164          *
 165          * @return        An error code
 166          * @param [in] touchEventInfo     The touch event information
 167          * @exception  E_SUCCESS                  The specified effect is successfully sent with a TouchMove event.
 168          * @exception  E_INVALID_STATE    The specified effect has not started as yet.
 169          * @exception  E_OPERATION_FAILED There is a runtime error in the OnTouchMoved() script method or the effect is time-based.
 170          */
 171         result FeedTouchMoveEvent(const Tizen::Ui::TouchEventInfo& touchEventInfo);
 172
 173         /**
 174          * Informs the effect of a TouchRelease event.
 175          *
 176          * @since 2.0
 177          *
 178          * @return        An error code
 179          * @param [in] touchEventInfo     The touch event information
 180          * @param [in] offset                     The effect will regard the touch position in @c touchEventInfo translated by @c offset
 181          * @exception  E_SUCCESS                  The specified effect is successfully sent with a TouchRelease event.
 182          * @exception  E_INVALID_STATE    The specified effect has not started as yet.
 183          * @exception  E_OPERATION_FAILED There is a runtime error in the OnTouchReleased() script method or the effect is time-based.
 184          */
 185         result FeedTouchReleaseEvent(const Tizen::Ui::TouchEventInfo& touchEventInfo, const Tizen::Graphics::Point& offset);
 186
 187         /**
 188          * Informs the effect of a TouchRelease event.
 189          *
 190          * @since 2.0
 191          *
 192          * @return        An error code
 193          * @param [in] touchEventInfo     The touch event information
 194          * @exception  E_SUCCESS                  The specified effect is successfully sent with a TouchRelease event.
 195          * @exception  E_INVALID_STATE    The specified effect has not started as yet.
 196          * @exception  E_OPERATION_FAILED There is a runtime error in the OnTouchReleased() script method or the effect is time-based.
 197          */
 198         result FeedTouchReleaseEvent(const Tizen::Ui::TouchEventInfo& touchEventInfo);
 199
 200         /**
 201          * Informs the effect of a TouchDoublePress event.
 202          *
 203          * @since 2.0
 204          *
 205          * @return        An error code
 206          * @param [in] touchEventInfo     The touch event information
 207          * @param [in] offset                     The effect will regard the touch position in @c touchEventInfo translated by @c offset
 208          * @exception  E_SUCCESS                  The specified effect is successfully sent with a TouchDoublePress event.
 209          * @exception  E_INVALID_STATE    The specified effect has not started as yet.
 210          * @exception  E_OPERATION_FAILED There is a runtime error in the OnTouchDoublePressed() script method or the effect is time-based.
 211          */
 212         result FeedTouchDoublePressEvent(const Tizen::Ui::TouchEventInfo& touchEventInfo, const Tizen::Graphics::Point& offset);
 213
 214         /**
 215          * Informs the effect of a TouchDoublePress event.
 216          *
 217          * @since 2.0
 218          *
 219          * @return        An error code
 220          * @param [in] touchEventInfo    The touch event information
 221          * @exception  E_SUCCESS                 The specified effect is successfully sent with a TouchDoublePress event.
 222          * @exception  E_INVALID_STATE   The specified effect has not started as yet.
 223          * @exception  E_OPERATION_FAILED There is a runtime error in the OnTouchDoublePressed() script method or the effect is time-based.
 224          */
 225         result FeedTouchDoublePressEvent(const Tizen::Ui::TouchEventInfo& touchEventInfo);
 226
 227         /**
 228          * Sets the effect's bitmap that is used as a graphical surface in scripts.
 229          *
 230          * @since 2.0
 231          *
 232          * @return        An error code
 233          * @param [in] bitmapId                   The bitmap ID to update
 234          * @param [in] bitmap                     The bitmap content
 235          * @exception  E_SUCCESS                  The bitmap is updated successfully.
 236          * @exception  E_OPERATION_FAILED Updating the bitmap contents has failed.
 237          */
 238         result SetBitmap(long bitmapId, const Tizen::Graphics::Bitmap& bitmap);
 239
 240         /**
 241          * Checks whether the effect is running.
 242          *
 243          * @since 2.0
 244          *
 245          * @return        @c true if the effect is running, @n
 246          *            else @c false
 247          */
 248         bool IsRunning(void) const;
 249
 250         /**
 251          * Gets the effect type.
 252          *
 253          * @since 2.0
 254          *
 255          * @return        The type of effect
 256          */
 257         EffectType GetType(void) const;
 258
 259         /**
 260          * Gets the name of the effect.
 261          *
 262          * @since 2.0
 263          *
 264          * @return        The name of the effect.
 265          */
 266         Tizen::Base::String GetName(void) const;
 267
 268         /**
 269          * Sets the IEffectsEventListener instance to get notified when the state of the effect is changed.
 270          *
 271          * @since 2.0
 272          *
 273          * @param [in] pListener         The event listener to set @n
 274          *                                                       If @c pListener is @c null, the status changes of this instance are not notified anymore.
 275          * @see GetEffectEventListener
 276          */
 277         void SetEffectEventListener(IEffectEventListener* pListener);
 278
 279         /**
 280          * Gets the IEffectsEventListener instance that is registered to the instance.
 281          *
 282          * @since 2.0
 283          *
 284          * @return      The event listener
 285          *
 286          * @see SetEffectEventListener
 287          */
 288         IEffectEventListener* GetEffectEventListener(void) const;
 289
 290         /**
 291          * Sets the IEffectsResourceProvider instance to get notified when resources are needed by the effect.
 292          *
 293          * @since 2.0
 294          *
 295          * @param [in] pProvider         The resource provider to provide the effect with bitmap resources @n
 296          *                                                       If @c pProvider is @c null, this instance will not display effects correctly.
 297          *
 298          * @see GetResourceProvider
 299          */
 300         void SetResourceProvider(IEffectResourceProvider* pProvider);
 301
 302         /**
 303          * Gets the IEffectsResourceProvider instance that is registered to the instance.
 304          *
 305          * @since 2.0
 306          *
 307          * @return   The resource provider
 308          *
 309          * @see SetResourceProvider
 310          */
 311         IEffectResourceProvider* GetResourceProvider(void) const;
 312
 313 protected:
 314         /**
 315          * This default constructor is intentionally declared as protected so that only the platform can create an instance.
 316          *
 317          * @since 2.0
 318          */
 319         Effect(void);
 320
 321         /**
 322          * This destructor overrides Tizen::Base::Object::~Object().
 323          *
 324          * @since 2.0
 325          */
 326         virtual ~Effect(void);
 327
 328         //
 329         // This method is for internal use only. Using this method can cause behavioral, security-related,
 330         // and consistency-related issues in the application.
 331         //
 332         //
 333         // This method is reserved and may change its name at any time without prior notice.
 334         //
 335         // @since 2.0
 336         //
 337         virtual void Effect_Reserved1(void) {}
 338
 339         //
 340         // This method is for internal use only. Using this method can cause behavioral, security-related,
 341         // and consistency-related issues in the application.
 342         //
 343         //
 344         // This method is reserved and may change its name at any time without prior notice.
 345         //
 346         // @since 2.0
 347         //
 348         virtual void Effect_Reserved2(void) {}
 349
 350         //
 351         // This method is for internal use only. Using this method can cause behavioral, security-related,
 352         // and consistency-related issues in the application.
 353         //
 354         //
 355         // This method is reserved and may change its name at any time without prior notice.
 356         //
 357         // @since 2.0
 358         //
 359         virtual void Effect_Reserved3(void) {}
 360
 361 private:
 362         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 363         Effect(const Effect& rhs);
 364
 365         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 366         Effect& operator=(const Effect& rhs);
 367
 368 private:
 369         friend class _EffectManagerImpl;
 370         friend class _EffectImpl;
 371         _EffectImpl* __pEffectImpl;
 372 }; //Effect
 373
 374 }}} // Tizen::Ui::Effects
 375
 376 #endif // _FUI_EFFECTS_EFFECT_H_
 377