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