dali-toolkit/devel-api/controls/popup/popup.h

   1 #ifndef __DALI_TOOLKIT_POPUP_H__
   2 #define __DALI_TOOLKIT_POPUP_H__
   3
   4 /*
   5  * Copyright (c) 2016 Samsung Electronics Co., Ltd.
   6  *
   7  * Licensed under the Apache License, Version 2.0 (the "License");
   8  * you may not use this file except in compliance with the License.
   9  * You may obtain a copy of the License at
  10  *
  11  * http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  *
  19  */
  20
  21 // INTERNAL INCLUDES
  22 #include <dali-toolkit/public-api/controls/control.h>
  23
  24 namespace Dali
  25 {
  26
  27 namespace Toolkit
  28 {
  29
  30 namespace Internal DALI_INTERNAL
  31 {
  32 class Popup;
  33 }
  34
  35 /**
  36  * @brief The Popup widget provides a configurable pop-up dialog with built-in layout of three main fields.
  37  *
  38  * Fields:
  39  * - Background Image
  40  *   - Title
  41  *   - Content
  42  *   - Footer
  43  *
  44  * Please see the programming guide for a detailed description of the Popup including examples.
  45  *
  46  * Signals
  47  * | %Signal Name      | Method                       |
  48  * |-------------------|------------------------------|
  49  * | touchedOutside    | @ref OutsideTouchedSignal()  |
  50  * | showing           | @ref ShowingSignal()         |
  51  * | shown             | @ref ShownSignal()           |
  52  * | hiding            | @ref HidingSignal()          |
  53  * | hidden            | @ref HiddenSignal()          |
  54  */
  55 class DALI_IMPORT_API Popup : public Control
  56 {
  57
  58 public:
  59
  60   /**
  61    * @brief The start and end property ranges for this control.
  62    */
  63   enum PropertyRange
  64   {
  65     PROPERTY_START_INDEX = Control::CONTROL_PROPERTY_END_INDEX + 1,
  66     PROPERTY_END_INDEX =   PROPERTY_START_INDEX + 1000              ///< Reserve property indices
  67   };
  68
  69   /**
  70    * @brief An enumeration of properties belonging to the Popup class.
  71    */
  72   struct Property
  73   {
  74     enum
  75     {
  76       TITLE = PROPERTY_START_INDEX, ///< name "title",                  type Property::Map
  77       CONTENT,                      ///< name "content",                type Property::Map
  78       FOOTER,                       ///< name "footer",                 type Property::Map
  79       DISPLAY_STATE,                ///< name "displayState",           type std::string
  80       TOUCH_TRANSPARENT,            ///< name "touchTransparent",       type bool
  81       TAIL_VISIBILITY,              ///< name "tailVisibility",         type bool
  82       TAIL_POSITION,                ///< name "tailPosition",           type Vector3
  83       CONTEXTUAL_MODE,              ///< name "contextualMode",         type std::string
  84       ANIMATION_DURATION,           ///< name "animationDuration",      type float
  85       ANIMATION_MODE,               ///< name "animationMode",          type std::string
  86       ENTRY_ANIMATION,              ///< name "entryAnimation",         type Property::Map
  87       EXIT_ANIMATION,               ///< name "exitAnimation",          type Property::Map
  88       AUTO_HIDE_DELAY,              ///< name "autoHideDelay",          type int
  89       BACKING_ENABLED,              ///< name "backingEnabled",         type bool
  90       BACKING_COLOR,                ///< name "backingColor",           type Vector4
  91       POPUP_BACKGROUND_IMAGE,       ///< name "popupBackgroundImage",   type std::string
  92       POPUP_BACKGROUND_BORDER,      ///< name "popupBackgroundBorder",  type Rect< int >,      Values are in the order: left, right, bottom, top
  93       TAIL_UP_IMAGE,                ///< name "tailUpImage",            type std::string
  94       TAIL_DOWN_IMAGE,              ///< name "tailDownImage",          type std::string
  95       TAIL_LEFT_IMAGE,              ///< name "tailLeftImage",          type std::string
  96       TAIL_RIGHT_IMAGE,             ///< name "tailRightImage",         type std::string
  97     };
  98   };
  99
 100   /**
 101    * The display states of the Popup.
 102    */
 103   enum DisplayState
 104   {
 105     SHOWING,           ///< The popup is transitioning in
 106     SHOWN,             ///< The popup is fully shown
 107     HIDING,            ///< The popup is transitioning out
 108     HIDDEN             ///< The popup is fully hidden
 109   };
 110
 111   /**
 112    * The animation mode within popup.
 113    * Choose from a predefined mode or "CUSTOM" to use the ANIMATION_IN and ANIMATION_OUT properties.
 114    */
 115   enum AnimationMode
 116   {
 117     NONE,              ///< No animation.
 118     ZOOM,              ///< Popup zooms in and out animating the scale property.
 119     FADE,              ///< Popup fades in and out.
 120     CUSTOM             ///< Use the EntryAnimation and ExitAnimation animation properties.
 121   };
 122
 123   /**
 124    * Types of contextual layout.
 125    * The Popup is positioned adjacent to it's parent in the direction specified by this mode.
 126    * NON_CONTEXTUAL disables any contextual positioning.
 127    */
 128   enum ContextualMode
 129   {
 130     NON_CONTEXTUAL,
 131     ABOVE,
 132     RIGHT,
 133     BELOW,
 134     LEFT
 135   };
 136
 137 public:
 138
 139   /**
 140    * @brief Creates an empty Popup handle.
 141    */
 142   Popup();
 143
 144   /**
 145    * @brief Create the Popup control.
 146    *
 147    * @return A handle to the Popup control.
 148    */
 149   static Popup New();
 150
 151   /**
 152    * @brief Destructor
 153    *
 154    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 155    */
 156   ~Popup();
 157
 158   /**
 159    * @brief Copy constructor.
 160    *
 161    * Creates another handle that points to the same real object
 162    * @param[in] handle Handle to the copied object
 163    */
 164   Popup( const Popup& handle );
 165
 166   /**
 167    * @brief Assignment operator.
 168    *
 169    * Changes this handle to point to another real object
 170    * @param[in] handle Handle to the object
 171    * @return A reference to this
 172    */
 173   Popup& operator=( const Popup& handle );
 174
 175   /**
 176    * @brief Downcast an Object handle to Popup.
 177    *
 178    * If handle points to a Popup the
 179    * downcast produces valid handle. If not the returned handle is left uninitialized.
 180    * @param[in] handle Handle to an object
 181    * @return handle to a Popup or an uninitialized handle
 182    */
 183   static Popup DownCast( BaseHandle handle );
 184
 185 public:
 186
 187   /**
 188    * @brief Sets a title for this Popup.
 189    *
 190    * @param[in] titleActor Any actor can be specified when using this method.
 191    */
 192   void SetTitle( Actor titleActor );
 193
 194   /**
 195    * @brief Gets the title actor for this Popup.
 196    *
 197    * @return The actor representing the title is returned.
 198    */
 199   Actor GetTitle() const;
 200
 201   /**
 202    * @brief Sets the content actor.
 203    * This can any actor type or heirarchy of actors.
 204    *
 205    * @param[in] content The actor to use.
 206    */
 207   void SetContent( Actor content );
 208
 209   /**
 210    * @brief Gets the actor currently used for the content.
 211    *
 212    * @return The content actor.
 213    */
 214   Actor GetContent() const;
 215
 216   /**
 217    * @brief Sets the actor to use for a footer in this Popup.
 218    *
 219    * @param[in] footer The footer actor to be added to this Popup
 220    */
 221   void SetFooter( Actor footer );
 222
 223   /**
 224    * @brief Gets the footer actor.
 225    *
 226    * @return The footer actor.
 227    */
 228   Actor GetFooter() const;
 229
 230   /**
 231    * @brief Sets the display state of Popup.
 232    *
 233    * There are 4 total display states.
 234    * Only 2 can be set, but all four can be read for better inspection of the current popup state.
 235    *
 236    * The other two states are getable, but not setable and are there for consistency.
 237    *
 238    * | Value    | Setting the state              | Getting the state              |
 239    * |----------|--------------------------------|--------------------------------|
 240    * | SHOWN    | Show the popup                 | The popup is fully shown       |
 241    * | HIDDEN   | Hide the popup                 | The popup is fully hidden      |
 242    * | SHOWING  |                                | The popup is transitioning in  |
 243    * | HIDING   |                                | The popup is transitioning out |
 244    *
 245    * All 4 state changes cause notifications via 4 respective signals that can be connected to.
 246    * @see GetDisplayState()
 247    *
 248    * @param[in] displayState The desired display state to change to.
 249    */
 250   void SetDisplayState( Toolkit::Popup::DisplayState displayState );
 251
 252   /**
 253    * @brief Gets the current state of the popup.
 254    *
 255    * This will also show if the popup is in the process of showing or hiding.
 256    *
 257    * @return The current state of the popup.
 258    */
 259   Toolkit::Popup::DisplayState GetDisplayState() const;
 260
 261 public:
 262
 263   typedef Signal< void () > TouchedOutsideSignalType;     ///< Touched outside signal type.
 264   typedef Signal< void () > DisplayStateChangeSignalType; ///< Used for signals emitted when the displayed state changes.
 265
 266   /**
 267    * @brief Signal emitted when user has touched outside of the Dialog.
 268    */
 269   TouchedOutsideSignalType& OutsideTouchedSignal();
 270
 271   /**
 272    * @brief Signal emitted when the Popup is starting to be shown.
 273    */
 274   DisplayStateChangeSignalType& ShowingSignal();
 275
 276   /**
 277    * @brief Signal emitted when the Popup has been fully displayed.
 278    */
 279   DisplayStateChangeSignalType& ShownSignal();
 280
 281   /**
 282    * @brief Signal emitted when the Popup is starting to be hidden.
 283    */
 284   DisplayStateChangeSignalType& HidingSignal();
 285
 286   /**
 287    * @brief Signal emitted when the Popup has been completely hidden.
 288    */
 289   DisplayStateChangeSignalType& HiddenSignal();
 290
 291 public: // Not intended for application developers
 292
 293   /**
 294    * @brief Creates a handle using the Toolkit::Internal implementation.
 295    *
 296    * @param[in]  implementation  The Control implementation.
 297    */
 298   DALI_INTERNAL Popup( Internal::Popup& implementation );
 299
 300   /**
 301    * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
 302    *
 303    * @param[in]  internal  A pointer to the internal CustomActor.
 304    */
 305   explicit DALI_INTERNAL Popup( Dali::Internal::CustomActor* internal );
 306 };
 307
 308 } // namespace Toolkit
 309
 310 } // namespace Dali
 311
 312 #endif // __DALI_TOOLKIT_POPUP_H__