base/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 DALI_IMPORT_API
  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 class Popup : public Control
  67 {
  68
  69 public:
  70
  71   //Signal Names
  72   static const char* const SIGNAL_TOUCHED_OUTSIDE; ///< name "touched-outside"
  73   static const char* const SIGNAL_HIDDEN;          ///< name "hidden"
  74
  75   /**
  76    * @brief Current popup state.
  77    */
  78   enum PopupState
  79   {
  80     POPUP_NONE,               ///< Init status
  81     POPUP_HIDE,               ///< Hidden (not visible)
  82     POPUP_SHOW,               ///< Shown (visible in default size)
  83   };
  84
  85   typedef SignalV2< void () > TouchedOutsideSignalV2; ///< Touched outside signal type.
  86   typedef SignalV2< void () > HiddenSignalV2;         ///< Hidden signal type.
  87
  88   /**
  89    * @brief Signal emitted when user has touched outside of the Dialog.
  90    */
  91   TouchedOutsideSignalV2& OutsideTouchedSignal();
  92
  93   /**
  94    * @brief Signal emitted when popup has been hidden.
  95    */
  96   HiddenSignalV2& HiddenSignal();
  97
  98 public:
  99
 100   /**
 101    * @brief Creates an empty Popup handle.
 102    */
 103   Popup();
 104
 105   /**
 106    * @brief Copy constructor.
 107    *
 108    * Creates another handle that points to the same real object
 109    * @param[in] handle Handle to the copied object
 110    */
 111   Popup( const Popup& handle );
 112
 113   /**
 114    * @brief Assignment operator.
 115    *
 116    * Changes this handle to point to another real object
 117    * @param[in] handle Handle to the object
 118    * @return A reference to this
 119    */
 120   Popup& operator=( const Popup& handle );
 121
 122   /**
 123    * @brief Destructor
 124    *
 125    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 126    */
 127   ~Popup();
 128
 129   /**
 130    * @brief Create the Poup control.
 131    *
 132    * @return A handle to the Popup control.
 133    */
 134   static Popup New();
 135
 136   /**
 137    * @brief Downcast an Object handle to Popup.
 138    *
 139    * If handle points to a Popup the
 140    * downcast produces valid handle. If not the returned handle is left uninitialized.
 141    * @param[in] handle Handle to an object
 142    * @return handle to a Popup or an uninitialized handle
 143    */
 144   static Popup DownCast( BaseHandle handle );
 145
 146 public:
 147
 148   /**
 149    * @brief Sets the background image for this Popup.
 150    *
 151    * The background is resized (stretched according to scale settings),
 152    * to the size of the Popup.
 153    *
 154    * @param[in] image The Background ImageActor to cover background
 155    */
 156   void SetBackgroundImage( Actor image );
 157
 158   /**
 159    * @brief Sets a title for this Popup.
 160    *
 161    * By default a TextView is created with following settings: black color, split-by-word multi-line policy and split exceed policy.
 162    *
 163    * @param[in] text The text to appear as the heading for this Popup
 164    */
 165   void SetTitle( const std::string& text );
 166
 167   /**
 168    * @brief Sets a title for this Popup.
 169    *
 170    * @param[in] titleActor The TextView to appear as the heading for this Popup
 171    */
 172   void SetTitle( TextView titleActor );
 173
 174   /**
 175    * @brief Gets the text (TextView) for this Popup.
 176    *
 177    * @return The TextView representing this popup is returned.
 178    */
 179   TextView GetTitle() const;
 180
 181   /**
 182    * @brief Adds a button to this Popup.
 183    *
 184    * Buttons are added to the bottom of the Popup and Centered.
 185    *
 186    * By default the first button added will have the focus, and the focus will
 187    * shift to other buttons based on the sequence in which they are added to the popup.
 188    *
 189    * @param[in] button The button to be added to this Popup
 190    */
 191   void AddButton( Button button );
 192
 193   /**
 194    * @brief Sets state of Popup, such as HIDE, and SHOW.
 195    *
 196    * The Popup will instantaneously jump to this state.
 197    *
 198    * @param[in] state The state of the popup
 199    */
 200   void SetState( PopupState state );
 201
 202   /**
 203    * @brief Sets state of Popup, such as HIDE, and SHOW.
 204    *
 205    * The Popup will smoothly animate to this state.
 206    *
 207    * @param[in] state The state of the popup
 208    * @param[in] duration The time to animate to this new state.
 209    */
 210   void SetState( PopupState state, float duration );
 211
 212   /**
 213    * @brief Gets the state of the popup.
 214    *
 215    * @return The state of the popup.
 216    */
 217   PopupState GetState() const;
 218
 219   /**
 220    * @brief Shows the popup.
 221    *
 222    * The Popup will animate to the SHOW state
 223    */
 224   void Show();
 225
 226   /**
 227    * @brief Hides the popup.
 228    *
 229    * The Popup will animate to the HIDE state
 230    */
 231   void Hide();
 232
 233   /**
 234    * @brief Shows the tail.
 235    *
 236    * The tail position is specified relative to it's Parent.
 237    * To display at top center for instace, pass:
 238    *
 239    * ParentOrigin::TOP_CENTER
 240    *
 241    * @note The tail images are defined inside PopupStyle as
 242    * tailUpImage, tailDownImage, tailLeftImage, and tailRightImage
 243    *
 244    * @param[in] position A position around the perimeter of the Parent.
 245    */
 246   void ShowTail(const Vector3& position);
 247
 248   /**
 249    * @brief Hides the tail.
 250    */
 251   void HideTail();
 252
 253 public: // Not intended for application developers
 254
 255   /**
 256    * @brief Creates a handle using the Toolkit::Internal implementation.
 257    *
 258    * @param[in]  implementation  The Control implementation.
 259    */
 260   Popup(Internal::Popup& implementation);
 261
 262   /**
 263    * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
 264    *
 265    * @param[in]  internal  A pointer to the internal CustomActor.
 266    */
 267   Popup( Dali::Internal::CustomActor* internal );
 268 };
 269
 270 } // namespace Toolkit
 271
 272 } // namespace Dali
 273
 274 #endif // __DALI_TOOLKIT_POPUP_H__