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

   1 #ifndef __DALI_TOOLKIT_POPUP_H__
   2 #define __DALI_TOOLKIT_POPUP_H__
   3
   4 /*
   5  * Copyright (c) 2014 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 #include <dali-toolkit/public-api/controls/text-view/text-view.h>
  24
  25 namespace Dali
  26 {
  27
  28 namespace Toolkit
  29 {
  30
  31 namespace Internal DALI_INTERNAL
  32 {
  33 class Popup;
  34 }
  35
  36 class Button;
  37
  38 /**
  39  * @brief Popup contains content that can come into focus when activated, and out of focus when deactivated.
  40  *
  41  * Content:
  42  *
  43  * The content within a popup consists of:
  44  *
  45  * 1. Title
  46  * 2. Buttons
  47  * 3. Background/Frame (i.e. Scale-9 image)
  48  * 4. Custom Content (Actors)
  49  *
  50  * All of which are optional.
  51  *
  52  * States:
  53  *
  54  * A popup can be in a number of states:
  55  *
  56  * 1. HIDE (invisible)
  57  * 2. SHOW (visible at normal size)
  58  * 3. SHOW_MAXIMIZED (visible occupying full parent size)
  59  * 4. Or custom defined.
  60  *
  61  * Transition Effects:
  62  *
  63  * A popup can use various custom transition effects, e.g.
  64  * Alpha fade, Scaling transition, position/rotation, shader effects.
  65  *
  66  * Signals
  67  * | %Signal Name      | Method                       |
  68  * |-------------------|------------------------------|
  69  * | touched-outside   | @ref OutsideTouchedSignal()  |
  70  * | hidden            | @ref HiddenSignal()          |
  71  */
  72 class DALI_IMPORT_API Popup : public Control
  73 {
  74
  75 public:
  76
  77   /**
  78    * @brief Current popup state.
  79    */
  80   enum PopupState
  81   {
  82     POPUP_NONE,               ///< Init status
  83     POPUP_HIDE,               ///< Hidden (not visible)
  84     POPUP_SHOW,               ///< Shown (visible in default size)
  85   };
  86
  87   typedef Signal< void () > TouchedOutsideSignalType; ///< Touched outside signal type.
  88   typedef Signal< void () > HiddenSignalType;         ///< Hidden signal type.
  89
  90   /**
  91    * @brief Signal emitted when user has touched outside of the Dialog.
  92    */
  93   TouchedOutsideSignalType& OutsideTouchedSignal();
  94
  95   /**
  96    * @brief Signal emitted when popup has been hidden.
  97    */
  98   HiddenSignalType& HiddenSignal();
  99
 100 public:
 101
 102   /**
 103    * @brief Creates an empty Popup handle.
 104    */
 105   Popup();
 106
 107   /**
 108    * @brief Copy constructor.
 109    *
 110    * Creates another handle that points to the same real object
 111    * @param[in] handle Handle to the copied object
 112    */
 113   Popup( const Popup& handle );
 114
 115   /**
 116    * @brief Assignment operator.
 117    *
 118    * Changes this handle to point to another real object
 119    * @param[in] handle Handle to the object
 120    * @return A reference to this
 121    */
 122   Popup& operator=( const Popup& handle );
 123
 124   /**
 125    * @brief Destructor
 126    *
 127    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 128    */
 129   ~Popup();
 130
 131   /**
 132    * @brief Create the Poup control.
 133    *
 134    * @return A handle to the Popup control.
 135    */
 136   static Popup New();
 137
 138   /**
 139    * @brief Downcast an Object handle to Popup.
 140    *
 141    * If handle points to a Popup the
 142    * downcast produces valid handle. If not the returned handle is left uninitialized.
 143    * @param[in] handle Handle to an object
 144    * @return handle to a Popup or an uninitialized handle
 145    */
 146   static Popup DownCast( BaseHandle handle );
 147
 148 public:
 149
 150   /**
 151    * @brief Sets the background image for this Popup.
 152    *
 153    * The background is resized (stretched according to scale settings),
 154    * to the size of the Popup.
 155    *
 156    * @param[in] image The Background ImageActor to cover background
 157    */
 158   void SetBackgroundImage( Actor image );
 159
 160   /**
 161    * @brief Sets a title for this Popup.
 162    *
 163    * By default a TextView is created with following settings: black color, split-by-word multi-line policy and split exceed policy.
 164    *
 165    * @param[in] text The text to appear as the heading for this Popup
 166    */
 167   void SetTitle( const std::string& text );
 168
 169   /**
 170    * @brief Sets a title for this Popup.
 171    *
 172    * @param[in] titleActor The TextView to appear as the heading for this Popup
 173    */
 174   void SetTitle( TextView titleActor );
 175
 176   /**
 177    * @brief Gets the text (TextView) for this Popup.
 178    *
 179    * @return The TextView representing this popup is returned.
 180    */
 181   TextView GetTitle() const;
 182
 183   /**
 184    * @brief Adds a button to this Popup.
 185    *
 186    * Buttons are added to the bottom of the Popup and Centered.
 187    *
 188    * By default the first button added will have the focus, and the focus will
 189    * shift to other buttons based on the sequence in which they are added to the popup.
 190    *
 191    * @param[in] button The button to be added to this Popup
 192    */
 193   void AddButton( Button button );
 194
 195   /**
 196    * @brief Sets state of Popup, such as HIDE, and SHOW.
 197    *
 198    * The Popup will instantaneously jump to this state.
 199    *
 200    * @param[in] state The state of the popup
 201    */
 202   void SetState( PopupState state );
 203
 204   /**
 205    * @brief Sets state of Popup, such as HIDE, and SHOW.
 206    *
 207    * The Popup will smoothly animate to this state.
 208    *
 209    * @param[in] state The state of the popup
 210    * @param[in] duration The time to animate to this new state.
 211    */
 212   void SetState( PopupState state, float duration );
 213
 214   /**
 215    * @brief Gets the state of the popup.
 216    *
 217    * @return The state of the popup.
 218    */
 219   PopupState GetState() const;
 220
 221   /**
 222    * @brief Shows the popup.
 223    *
 224    * The Popup will animate to the SHOW state
 225    */
 226   void Show();
 227
 228   /**
 229    * @brief Hides the popup.
 230    *
 231    * The Popup will animate to the HIDE state
 232    */
 233   void Hide();
 234
 235   /**
 236    * @brief Shows the tail.
 237    *
 238    * The tail position is specified relative to it's Parent.
 239    * To display at top center for instace, pass:
 240    *
 241    * ParentOrigin::TOP_CENTER
 242    *
 243    * @note The tail images are defined inside PopupStyle as
 244    * tailUpImage, tailDownImage, tailLeftImage, and tailRightImage
 245    *
 246    * @param[in] position A position around the perimeter of the Parent.
 247    */
 248   void ShowTail(const Vector3& position);
 249
 250   /**
 251    * @brief Hides the tail.
 252    */
 253   void HideTail();
 254
 255   /**
 256    * @brief Flag the popup as dirty for relayout
 257    */
 258   void MarkDirtyForRelayout();
 259
 260 public: // Not intended for application developers
 261
 262   /**
 263    * @brief Creates a handle using the Toolkit::Internal implementation.
 264    *
 265    * @param[in]  implementation  The Control implementation.
 266    */
 267   DALI_INTERNAL Popup(Internal::Popup& implementation);
 268
 269   /**
 270    * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
 271    *
 272    * @param[in]  internal  A pointer to the internal CustomActor.
 273    */
 274   explicit DALI_INTERNAL Popup( Dali::Internal::CustomActor* internal );
 275 };
 276
 277 } // namespace Toolkit
 278
 279 } // namespace Dali
 280
 281 #endif // __DALI_TOOLKIT_POPUP_H__