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