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