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