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          * Sets the item provider that creates and deletes the items from the %Gallery control.
 218          *
 219          * @since               2.0
 220          *
 221          * @return              An error code
 222          * @param[in]   provider                The item provider to create and delete items
 223          * @exception   E_SUCCESS                       The method is successful.
 224          * @remark              If an item provider is not set for the %Gallery control, the method does not work. @n
 225          *              The item provider should be allocated on a heap memory.
 226          */
 227         result SetItemProvider(IGalleryItemProvider& provider);
 228
 229         /**
 230          * Adds an IGalleryEventListener instance. @n
 231          * The added listener can listen to the item events when they are fired.
 232          *
 233          * @since               2.0
 234          *
 235          * @param[in]   listener                The listener to be added
 236          */
 237         void AddGalleryEventListener(IGalleryEventListener& listener);
 238
 239         /**
 240          * Removes an IGalleryEventListener instance. @n
 241          * The removed listener cannot listen to events when they are fired.
 242          *
 243          * @since               2.0
 244          *
 245          * @param[in]   listener                The listener to be removed
 246          */
 247         void RemoveGalleryEventListener(IGalleryEventListener& listener);
 248
 249         /**
 250          * Gets the index of the current item.
 251          *
 252          * @since               2.0
 253          *
 254          * @return              The current item index of the %Gallery control
 255      * @remarks     The specific error code can be accessed using the GetLastResult() method.
 256          */
 257         int GetCurrentItemIndex(void) const;
 258
 259         /**
 260          * Sets the index of the current item.
 261          *
 262          * @since               2.0
 263          *
 264          * @return              An error code
 265          * @param[in]   index                   The index of the item
 266          * @exception   E_SUCCESS               The method is successful.
 267          * @exception   E_OUT_OF_RANGE  The specified @c index is out of range.
 268          * @exception   E_SYSTEM                A system error has occurred.
 269          *
 270          */
 271         result SetCurrentItemIndex(int index);
 272
 273         /**
 274          * Gets the total number of items.
 275          *
 276          * @since       2.0
 277          *
 278          * @return      The total number of items, @n
 279          *                      else @c -1 if an error occurs
 280          */
 281         int GetItemCount(void) const;
 282
 283         /**
 284          * Refreshes the item at the specified index.
 285          *
 286          * @since               2.0
 287          *
 288          * @return              An error code
 289          * @param[in]   itemIndex                       The index of the item to be refreshed
 290          * @param[in]   type                    The type of change for an item
 291          * @exception   E_SUCCESS                               The method is successful.
 292          * @exception   E_OUT_OF_RANGE  The specified @c index is out of range.
 293          * @exception   E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation.
 294          * @exception   E_SYSTEM                                A system error has occurred.
 295          */
 296         result RefreshGallery(int itemIndex, GalleryRefreshType type);
 297
 298         /**
 299          * Updates all the items of a list.
 300          *
 301          * @since         2.0
 302          *
 303          * @return    An error code
 304          * @exception   E_SUCCESS                       The method is successful.
 305          * @exception E_INVALID_OPERATION  The current state of the instance prohibits the execution of the specified operation.
 306          * @exception E_SYSTEM             A system error has occurred.
 307          * @remarks   This method clears items in the list and reinvokes methods of the item provider to fill the list.
 308          */
 309         result UpdateGallery(void);
 310
 311         /**
 312          * Sets the text of the empty %Gallery control.
 313          *
 314          * @since               2.0
 315          *
 316          * @return              An error code
 317          * @param[in]   text                            The text of the empty %Gallery control
 318          * @exception   E_SUCCESS                       The method is successful.
 319          * @exception   E_SYSTEM                        A system error has occurred.
 320          */
 321         result SetTextOfEmptyGallery(const Tizen::Base::String& text);
 322
 323         /**
 324          * Gets the text of the empty %Gallery control.
 325          *
 326          * @since               2.0
 327          *
 328          * @return              The text of the empty %Gallery control
 329          * @exception   E_SUCCESS                       The method is successful.
 330          * @exception   E_SYSTEM                        A system error has occurred.
 331          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 332          */
 333         Tizen::Base::String GetTextOfEmptyGallery(void) const;
 334
 335         /**
 336          * Sets the background bitmap of the %Gallery control.
 337          *
 338          * @since               2.0
 339          *
 340          * @param[in]   pBitmap                         The bitmap of the empty %Gallery control
 341          * @exception   E_SUCCESS                       The method is successful.
 342          * @exception   E_SYSTEM                        A system error has occurred.
 343          * @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.
 344          * @remarks             The background bitmap has a priority over the background color. When both the background bitmap and the background color are specified,
 345          *                              only the bitmap is displayed.
 346          */
 347         result SetBitmapOfEmptyGallery(const Tizen::Graphics::Bitmap* pBitmap);
 348
 349         /**
 350          * Sets the slide show transition animation type.
 351          *
 352          * @since               2.0
 353          *
 354          * @param[in] animation                The animation type of the %Gallery control
 355          * @exception E_SUCCESS                The method is successful.
 356          * @exception E_UNSUPPORTED_OPERATION  This operation is not supported.
 357          * @exception E_SYSTEM                 A system error has occurred.
 358          * @remarks   The method is not supported in 16-bit devices.
 359          */
 360         result SetSlideShowAnimation(GalleryAnimation animation);
 361
 362         /**
 363          * Gets the transition animation type of the slide show.
 364          *
 365          * @since               2.0
 366          *
 367          * @return    The animation type of a %Gallery control
 368          * @exception E_SUCCESS                The method is successful.
 369          * @exception E_UNSUPPORTED_OPERATION  This operation is not supported.
 370          * @exception E_SYSTEM                 A system error has occurred.
 371          * @remarks   The specific error code can be accessed using the GetLastResult() method.
 372          * @remarks   The method is not supported in 16-bit devices.
 373          */
 374         GalleryAnimation GetSlideShowAnimation(void) const;
 375
 376         /**
 377          * Sets the duration of the slide show transition animation.
 378          *
 379          * @since               2.0
 380          *
 381          * @param[in]   duration        The animation duration
 382          * @exception   E_SUCCESS                       The method is successful.
 383          * @exception   E_OUT_OF_RANGE          The specified @c duration is out of the possible duration range. @n
 384          *                              The specified duration should be greater than or equal to 300 or less than or equals to 20000.
 385          * @exception   E_SYSTEM                        A system error has occurred.
 386          * @remarks     The unit of the duration is in milliseconds.@n
 387          *                              The default animation duration is different for each slide show animation type.
 388          */
 389         result SetSlideShowAnimationDuration(int duration);
 390
 391         /**
 392          * Gets the transition animation duration of the %Gallery control.
 393          *
 394          * @since               2.0
 395          *
 396          * @return      The animation duration, @n
 397          *              else @c -1 if an error occurs
 398          * @exception   E_SUCCESS               The method is successful.
 399          * @exception   E_SYSTEM                A system error has occurred.
 400          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 401          */
 402         int GetSlideShowAnimationDuration(void) const;
 403
 404         /**
 405          * Sets the duration of the slide-show item view.
 406          *
 407          * @since               2.0
 408          *
 409          * @param[in]   duration                The item view duration
 410          * @exception   E_SUCCESS                       The method is successful.
 411          * @exception   E_OUT_OF_RANGE  The specified @c duration is out of possible duration range. @n
 412          *                                                              - The specified @c duration should be greater than 10.
 413          * @exception   E_SYSTEM                        A system error has occurred.
 414          * @remarks     The unit of the duration is in milliseconds.@n
 415          *                              The default animation duration is different for each slide show animation type.
 416          */
 417         result SetSlideShowViewDuration(int duration);
 418
 419         /**
 420          * Gets the duration of the slide-show item view.
 421          *
 422          * @since               2.0
 423          *
 424          * @return              The item view duration, @n
 425          *                              else @c -1 if an error occurs
 426          * @exception   E_SUCCESS                       The method is successful.
 427          * @exception   E_SYSTEM                        A system error has occurred.
 428          * @remarks             The specific error code can be accessed using @c GetLastResult() method.
 429          */
 430         int GetSlideShowViewDuration(void) const;
 431
 432         /**
 433          * Starts the slide show.
 434          *
 435          * @since               2.0
 436          *
 437          * @return              An error code
 438          * @param[in]   repeat                       The repeat status
 439          * @exception   E_SUCCESS                       The method is successful.
 440          * @exception   E_INVALID_OPERATION  The current state of the instance prohibits the execution of the specified operation.
 441          * @exception   E_SYSTEM                     A system error has occurred.
 442          */
 443         result StartSlideShow(bool repeat = false);
 444
 445         /**
 446          * Stops the slide show.
 447          *
 448          * @since               2.0
 449          *
 450          * @return              An error code
 451          * @exception   E_SUCCESS                       The method is successful.
 452          * @exception   E_INVALID_OPERATION  The current state of the instance prohibits the execution of the specified operation.
 453          * @exception   E_SYSTEM                     A system error has occurred.
 454          */
 455         result StopSlideShow(void) const;
 456
 457         /**
 458          * Checks whether the slide show has started.
 459          *
 460          * @since               2.0
 461          *
 462          * @return              @c true if the slide show is running, @n
 463          *                              else @c false
 464          * @exception   E_SUCCESS                       The method is successful.
 465          * @exception   E_SYSTEM                        A system error has occurred.
 466          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 467          */
 468         bool IsSlideShowStarted(void) const;
 469
 470         /**
 471          * Enables or disables the image zooming.
 472          *
 473          * @since               2.0
 474          *
 475          * @return              An error code
 476          * @param[in]   enable                          Set to @c true to enable zooming, @n
 477          *                                                                      else @c false
 478          * @exception   E_SUCCESS                       The method is successful.
 479          * @exception   E_SYSTEM                        A system error has occurred.
 480          * @remarks             When enabled, the user can enter the zoom mode by double-clicking or pinching the current image.
 481          */
 482         result SetZoomingEnabled(bool enable);
 483
 484         /**
 485          * Checks whether zooming is enabled.
 486          *
 487          * @since               2.0
 488          *
 489          * @return              @c true if zooming is enabled, @n
 490          *                              else @c false
 491          * @exception   E_SUCCESS                       The method is successful.
 492          * @exception   E_SYSTEM                        A system error has occurred.
 493          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 494          */
 495         bool IsZoomingEnabled(void) const;
 496
 497         /**
 498          * Sets the background color of the %Gallery control.
 499          *
 500          * @since       2.0
 501          *
 502          * @return      An error code
 503          * @param[in]   color   The background color
 504          * @exception   E_SUCCESS               The method is successful.
 505          * @exception   E_SYSTEM                A system error has occurred.
 506          * @remarks     The method ignores the alpha value of the @c color parameter and sets the alpha value to 255.
 507          */
 508         result SetBackgroundColor(const Tizen::Graphics::Color& color);
 509
 510         /**
 511          * Gets the background color of the %Gallery control.
 512          *
 513          * @since       2.0
 514          *
 515          * @return      The background color, @n
 516          *              else RGBA(0, 0, 0, 0) if an error occurs
 517          * @exception   E_SUCCESS                       The method is successful.
 518          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 519          */
 520         Tizen::Graphics::Color GetBackgroundColor(void) const;
 521
 522 private:
 523         //
 524         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 525         //
 526         Gallery(const Gallery& rhs);
 527
 528         //
 529         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 530         //
 531         Gallery& operator =(const Gallery& rhs);
 532
 533 protected:
 534         friend class _GalleryImpl;
 535 }; // Gallery
 536
 537 }}} // Tizen::Ui::Controls
 538
 539 #endif // _FUI_CTRL_GALLERY_H_