inc/FUiCtrlGallery.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
   4 //
   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
   8 //
   9 //     http://floralicense.org/license/
  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        FUiCtrlGallery.h
  20  * @brief       This is the header file for the %Gallery class.
  21  *
  22  * This header file contains the declarations of the %Gallery class and its helper classes.
  23  */
  24
  25 #ifndef _FUI_CTRL_GALLERY_H_
  26 #define _FUI_CTRL_GALLERY_H_
  27
  28 #include <FBaseObject.h>
  29 #include <FBaseTypes.h>
  30 #include <FBaseString.h>
  31 #include <FGrpRectangle.h>
  32 #include <FGrpDimension.h>
  33 #include <FGrpBitmap.h>
  34 #include <FUiControl.h>
  35 #include <FUiContainer.h>
  36 #include <FUiCtrlGalleryItem.h>
  37 #include <FUiCtrlGalleryTypes.h>
  38 #include <FUiCtrlIGalleryItemProvider.h>
  39 #include <FUiCtrlIGalleryEventListener.h>
  40
  41 namespace Tizen { namespace Ui { namespace Controls
  42 {
  43 /**
  44  * @class       Gallery
  45  * @brief       This class defines the common behavior of a %Gallery control.
  46  *
  47  * @since       2.0
  48  *
  49  * The %Gallery class displays an image viewer that contains a collection of images (1
  50  * image at a time) in a horizontally scrolling list. It also supports a slide
  51  * show that automatically displays all the images consecutively.
  52  *
  53  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/implementing_gallery.htm">Gallery</a>.
  54  *
  55  * The following example demonstrates how to use the %Gallery class.
  56  *
  57  * @code
  58 // Sample code for GallerySample.h
  59 #include <FUi.h>
  60
  61 class GallerySample
  62         : public Tizen::Ui::Controls::Form
  63         , public Tizen::Ui::Controls::IGalleryItemProvider
  64         , public Tizen::Ui::Controls::IGalleryEventListener
  65 {
  66 public:
  67         GallerySample(void)
  68         : __pGallery(null){}
  69
  70         bool Initialize(void);
  71         virtual result OnInitializing(void);
  72
  73         //IGalleryItemProvider
  74         virtual Tizen::Ui::Controls::GalleryItem* CreateItem (int index);
  75         virtual bool DeleteItem (int index, Tizen::Ui::Controls::GalleryItem *pItem);
  76         virtual int GetItemCount(void);
  77
  78         // IGalleryEventListener
  79         virtual void OnGalleryCurrentItemChanged(Tizen::Ui::Controls::Gallery &gallery, int index);
  80         virtual void OnGalleryItemClicked(Tizen::Ui::Controls::Gallery &gallery, int index);
  81         virtual void OnGallerySlideShowStarted(Tizen::Ui::Controls::Gallery& gallery);
  82         virtual void OnGallerySlideShowStopped(Tizen::Ui::Controls::Gallery& gallery);
  83
  84 private:
  85         Tizen::Ui::Controls::Gallery* __pGallery;
  86 };
  87  *      @endcode
  88  *
  89  *      @code
  90 // Sample code for GallerySample.cpp
  91 #include <FApp.h>
  92 #include <FGraphics.h>
  93
  94 #include "GallerySample.h"
  95
  96 using namespace Tizen::App;
  97 using namespace Tizen::Ui;
  98 using namespace Tizen::Ui::Controls;
  99 using namespace Tizen::Graphics;
 100
 101 bool
 102 GallerySample::Initialize(void)
 103 {
 104         Construct(FORM_STYLE_NORMAL);
 105         return true;
 106 }
 107
 108 result
 109 GallerySample::OnInitializing(void)
 110 {
 111         result r = E_SUCCESS;
 112
 113         // Creates an instance of Gallery
 114         __pGallery = new Gallery();
 115         __pGallery->Construct(GetBounds());
 116         __pGallery->SetItemProvider(*this);
 117         __pGallery->AddGalleryEventListener(*this);
 118
 119         AddControl(*__pGallery);
 120
 121         return r;
 122 }
 123
 124 // IGalleryItemProvider implementation
 125 GalleryItem*
 126 GallerySample::CreateItem(int index)
 127 {
 128         // Gets an instance of Bitmap
 129         AppResource* pAppResource = Application::GetInstance()->GetAppResource();
 130         Bitmap* pImageTemp = pAppResource->GetBitmapN(L"Image.jpg");
 131
 132         // Creates an instance of GalleryItem and registers the bitmap to the gallery item
 133         GalleryItem* pGallery = new GalleryItem();
 134         pGallery->Construct(*pImageTemp);
 135
 136         // Deallocates the bitmap
 137         delete pImageTemp;
 138
 139         return pGallery;
 140 }
 141
 142 bool
 143 GallerySample::DeleteItem(int index, GalleryItem *pItem)
 144 {
 145         delete pItem;
 146         return true;
 147 }
 148
 149 int
 150 GallerySample::GetItemCount(void)
 151 {
 152         return 1;
 153 }
 154
 155 // IGalleryEventListener implementation
 156 void
 157  GallerySample::OnGalleryCurrentItemChanged(Gallery &gallery, int index)
 158 {
 159         // ....
 160 }
 161
 162 void
 163 GallerySample::OnGalleryItemClicked(Gallery &gallery, int index)
 164 {
 165         // ....
 166 }
 167
 168 void
 169 GallerySample::OnGallerySlideShowStarted(Gallery& gallery)
 170 {
 171         // ....
 172 }
 173
 174 void
 175 GallerySample::OnGallerySlideShowStopped(Gallery& gallery)
 176 {
 177         // ....
 178 }
 179  * @endcode
 180  */
 181
 182 class _OSP_EXPORT_ Gallery
 183         : public Tizen::Ui::Control
 184 {
 185 public:
 186         /**
 187          * The object is not fully constructed after this constructor is called. For full construction, the Construct() method must be called right after calling this constructor.
 188          *
 189          * @since 2.0
 190          */
 191         Gallery(void);
 192
 193         /**
 194          * This destructor overrides Tizen::Base::Object::~Object().
 195          *
 196          * @since 2.0
 197          */
 198         virtual ~Gallery(void);
 199
 200 public:
 201         /**
 202          * Initializes this instance of %Gallery with the specified parameter.
 203          *
 204          * @since               2.0
 205          *
 206          * @return              An error code
 207          * @param[in]   rect            An instance of the Graphics::Rectangle class @n
 208          *                                                              This instance represents the x and y coordinates of the top-left corner of the created %Gallery control along with the
 209          *                                                                      width and height.
 210          * @exception   E_SUCCESS                       The method is successful.
 211          * @exception   E_INVALID_ARG   The specified input parameter is invalid.
 212          * @exception   E_SYSTEM                        A system error has occurred.
 213          */
 214         result Construct(const Tizen::Graphics::Rectangle& rect);
 215
 216         /**
 217          * Initializes this instance of %Gallery with the specified parameter.
 218          *
 219          * @since               2.1
 220          *
 221          * @return              An error code
 222          * @param[in]   rect            An instance of the Graphics::FloatRectangle class @n
 223          *                                                              This instance represents the x and y coordinates of the top-left corner of the created %Gallery control along with the
 224          *                                                                      width and height.
 225          * @exception   E_SUCCESS                       The method is successful.
 226          * @exception   E_INVALID_ARG   The specified input parameter is invalid.
 227          * @exception   E_SYSTEM                        A system error has occurred.
 228          */
 229         result Construct(const Tizen::Graphics::FloatRectangle& rect);
 230
 231         /**
 232          * Sets the item provider that creates and deletes the items from the %Gallery control.
 233          *
 234          * @since               2.0
 235          *
 236          * @return              An error code
 237          * @param[in]   provider                The item provider to create and delete items
 238          * @exception   E_SUCCESS                       The method is successful.
 239          * @remark              If an item provider is not set for the %Gallery control, the method does not work. @n
 240          *              The item provider should be allocated on a heap memory.
 241          */
 242         result SetItemProvider(IGalleryItemProvider& provider);
 243
 244         /**
 245          * Adds an IGalleryEventListener instance. @n
 246          * The added listener can listen to the item events when they are fired.
 247          *
 248          * @since               2.0
 249          *
 250          * @param[in]   listener                The listener to be added
 251          */
 252         void AddGalleryEventListener(IGalleryEventListener& listener);
 253
 254         /**
 255          * Removes an IGalleryEventListener instance. @n
 256          * The removed listener cannot listen to events when they are fired.
 257          *
 258          * @since               2.0
 259          *
 260          * @param[in]   listener                The listener to be removed
 261          */
 262         void RemoveGalleryEventListener(IGalleryEventListener& listener);
 263
 264         /**
 265          * Gets the index of the current item.
 266          *
 267          * @since               2.0
 268          *
 269          * @return              The current item index of the %Gallery control
 270      * @remarks     The specific error code can be accessed using the GetLastResult() method.
 271          */
 272         int GetCurrentItemIndex(void) const;
 273
 274         /**
 275          * Sets the index of the current item.
 276          *
 277          * @since               2.0
 278          *
 279          * @return              An error code
 280          * @param[in]   index                   The index of the item
 281          * @exception   E_SUCCESS               The method is successful.
 282          * @exception   E_OUT_OF_RANGE  The specified @c index is out of range.
 283          * @exception   E_SYSTEM                A system error has occurred.
 284          *
 285          */
 286         result SetCurrentItemIndex(int index);
 287
 288         /**
 289          * Gets the total number of items.
 290          *
 291          * @since       2.0
 292          *
 293          * @return      The total number of items, @n
 294          *                      else @c -1 if an error occurs
 295          */
 296         int GetItemCount(void) const;
 297
 298         /**
 299          * Refreshes the item at the specified index.
 300          *
 301          * @since               2.0
 302          *
 303          * @return              An error code
 304          * @param[in]   itemIndex                       The index of the item to be refreshed
 305          * @param[in]   type                    The type of change for an item
 306          * @exception   E_SUCCESS                               The method is successful.
 307          * @exception   E_OUT_OF_RANGE  The specified @c index is out of range.
 308          * @exception   E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation.
 309          * @exception   E_SYSTEM                                A system error has occurred.
 310          */
 311         result RefreshGallery(int itemIndex, GalleryRefreshType type);
 312
 313         /**
 314          * Updates all the items of a list.
 315          *
 316          * @since         2.0
 317          *
 318          * @return    An error code
 319          * @exception   E_SUCCESS                       The method is successful.
 320          * @exception E_INVALID_OPERATION  The current state of the instance prohibits the execution of the specified operation.
 321          * @exception E_SYSTEM             A system error has occurred.
 322          * @remarks   This method clears items in the list and reinvokes methods of the item provider to fill the list.
 323          */
 324         result UpdateGallery(void);
 325
 326         /**
 327          * Sets the text of the empty %Gallery control.
 328          *
 329          * @since               2.0
 330          *
 331          * @return              An error code
 332          * @param[in]   text                            The text of the empty %Gallery control
 333          * @exception   E_SUCCESS                       The method is successful.
 334          * @exception   E_SYSTEM                        A system error has occurred.
 335          */
 336         result SetTextOfEmptyGallery(const Tizen::Base::String& text);
 337
 338         /**
 339          * Gets the text of the empty %Gallery control.
 340          *
 341          * @since               2.0
 342          *
 343          * @return              The text of the empty %Gallery control
 344          * @exception   E_SUCCESS                       The method is successful.
 345          * @exception   E_SYSTEM                        A system error has occurred.
 346          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 347          */
 348         Tizen::Base::String GetTextOfEmptyGallery(void) const;
 349
 350         /**
 351          * Sets the background bitmap of the %Gallery control.
 352          *
 353          * @since               2.0
 354          *
 355          * @param[in]   pBitmap                         The bitmap of the empty %Gallery control
 356          * @exception   E_SUCCESS                       The method is successful.
 357          * @exception   E_SYSTEM                        A system error has occurred.
 358          * @remarks             When @c pBitmap is @c null, the %Gallery control does not have a background bitmap. The default value for the background bitmap is @c null.
 359          * @remarks             The background bitmap has a priority over the background color. When both the background bitmap and the background color are specified,
 360          *                              only the bitmap is displayed.
 361          */
 362         result SetBitmapOfEmptyGallery(const Tizen::Graphics::Bitmap* pBitmap);
 363
 364         /**
 365          * Sets the slide show transition animation type.
 366          *
 367          * @since               2.0
 368          *
 369          * @param[in] animation                The animation type of the %Gallery control
 370          * @exception E_SUCCESS                The method is successful.
 371          * @exception E_UNSUPPORTED_OPERATION  This operation is not supported.
 372          * @exception E_SYSTEM                 A system error has occurred.
 373          * @remarks   The method is not supported in 16-bit devices.
 374          */
 375         result SetSlideShowAnimation(GalleryAnimation animation);
 376
 377         /**
 378          * Gets the transition animation type of the slide show.
 379          *
 380          * @since               2.0
 381          *
 382          * @return    The animation type of a %Gallery control
 383          * @exception E_SUCCESS                The method is successful.
 384          * @exception E_UNSUPPORTED_OPERATION  This operation is not supported.
 385          * @exception E_SYSTEM                 A system error has occurred.
 386          * @remarks   The specific error code can be accessed using the GetLastResult() method.
 387          * @remarks   The method is not supported in 16-bit devices.
 388          */
 389         GalleryAnimation GetSlideShowAnimation(void) const;
 390
 391         /**
 392          * Sets the duration of the slide show transition animation.
 393          *
 394          * @since               2.0
 395          *
 396          * @param[in]   duration        The animation duration
 397          * @exception   E_SUCCESS                       The method is successful.
 398          * @exception   E_OUT_OF_RANGE          The specified @c duration is out of the possible duration range. @n
 399          *                              The specified duration should be greater than or equal to 300 or less than or equals to 20000.
 400          * @exception   E_SYSTEM                        A system error has occurred.
 401          * @remarks     The unit of the duration is in milliseconds.@n
 402          *                              The default animation duration is different for each slide show animation type.
 403          */
 404         result SetSlideShowAnimationDuration(int duration);
 405
 406         /**
 407          * Gets the transition animation duration of the %Gallery control.
 408          *
 409          * @since               2.0
 410          *
 411          * @return      The animation duration, @n
 412          *              else @c -1 if an error occurs
 413          * @exception   E_SUCCESS               The method is successful.
 414          * @exception   E_SYSTEM                A system error has occurred.
 415          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 416          */
 417         int GetSlideShowAnimationDuration(void) const;
 418
 419         /**
 420          * Sets the duration of the slide-show item view.
 421          *
 422          * @since               2.0
 423          *
 424          * @param[in]   duration                The item view duration
 425          * @exception   E_SUCCESS                       The method is successful.
 426          * @exception   E_OUT_OF_RANGE  The specified @c duration is out of possible duration range. @n
 427          *                                                              - The specified @c duration should be greater than 10.
 428          * @exception   E_SYSTEM                        A system error has occurred.
 429          * @remarks     The unit of the duration is in milliseconds.@n
 430          *                              The default animation duration is different for each slide show animation type.
 431          */
 432         result SetSlideShowViewDuration(int duration);
 433
 434         /**
 435          * Gets the duration of the slide-show item view.
 436          *
 437          * @since               2.0
 438          *
 439          * @return              The item view duration, @n
 440          *                              else @c -1 if an error occurs
 441          * @exception   E_SUCCESS                       The method is successful.
 442          * @exception   E_SYSTEM                        A system error has occurred.
 443          * @remarks             The specific error code can be accessed using @c GetLastResult() method.
 444          */
 445         int GetSlideShowViewDuration(void) const;
 446
 447         /**
 448          * Starts the slide show.
 449          *
 450          * @since               2.0
 451          *
 452          * @return              An error code
 453          * @param[in]   repeat                       The repeat status
 454          * @exception   E_SUCCESS                       The method is successful.
 455          * @exception   E_INVALID_OPERATION  The current state of the instance prohibits the execution of the specified operation.
 456          * @exception   E_SYSTEM                     A system error has occurred.
 457          */
 458         result StartSlideShow(bool repeat = false);
 459
 460         /**
 461          * Stops the slide show.
 462          *
 463          * @since               2.0
 464          *
 465          * @return              An error code
 466          * @exception   E_SUCCESS                       The method is successful.
 467          * @exception   E_INVALID_OPERATION  The current state of the instance prohibits the execution of the specified operation.
 468          * @exception   E_SYSTEM                     A system error has occurred.
 469          */
 470         result StopSlideShow(void) const;
 471
 472         /**
 473          * Checks whether the slide show has started.
 474          *
 475          * @since               2.0
 476          *
 477          * @return              @c true if the slide show is running, @n
 478          *                              else @c false
 479          * @exception   E_SUCCESS                       The method is successful.
 480          * @exception   E_SYSTEM                        A system error has occurred.
 481          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 482          */
 483         bool IsSlideShowStarted(void) const;
 484
 485         /**
 486          * Enables or disables the image zooming.
 487          *
 488          * @since               2.0
 489          *
 490          * @return              An error code
 491          * @param[in]   enable                          Set to @c true to enable zooming, @n
 492          *                                                                      else @c false
 493          * @exception   E_SUCCESS                       The method is successful.
 494          * @exception   E_SYSTEM                        A system error has occurred.
 495          * @remarks             When enabled, the user can enter the zoom mode by double-clicking or pinching the current image.
 496          */
 497         result SetZoomingEnabled(bool enable);
 498
 499         /**
 500          * Checks whether zooming is enabled.
 501          *
 502          * @since               2.0
 503          *
 504          * @return              @c true if zooming is enabled, @n
 505          *                              else @c false
 506          * @exception   E_SUCCESS                       The method is successful.
 507          * @exception   E_SYSTEM                        A system error has occurred.
 508          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 509          */
 510         bool IsZoomingEnabled(void) const;
 511
 512         /**
 513          * Sets the background color of the %Gallery control.
 514          *
 515          * @since       2.0
 516          *
 517          * @return      An error code
 518          * @param[in]   color   The background color
 519          * @exception   E_SUCCESS               The method is successful.
 520          * @exception   E_SYSTEM                A system error has occurred.
 521          * @remarks     The method ignores the alpha value of the @c color parameter and sets the alpha value to 255.
 522          */
 523         result SetBackgroundColor(const Tizen::Graphics::Color& color);
 524
 525         /**
 526          * Gets the background color of the %Gallery control.
 527          *
 528          * @since       2.0
 529          *
 530          * @return      The background color, @n
 531          *              else RGBA(0, 0, 0, 0) if an error occurs
 532          * @exception   E_SUCCESS                       The method is successful.
 533          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 534          */
 535         Tizen::Graphics::Color GetBackgroundColor(void) const;
 536
 537 private:
 538         //
 539         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 540         //
 541         Gallery(const Gallery& rhs);
 542
 543         //
 544         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 545         //
 546         Gallery& operator =(const Gallery& rhs);
 547
 548 protected:
 549         friend class _GalleryImpl;
 550 }; // Gallery
 551
 552 }}} // Tizen::Ui::Controls
 553
 554 #endif // _FUI_CTRL_GALLERY_H_