#define __DALI_TOOLKIT_POPUP_H__
/*
- * Copyright (c) 2015 Samsung Electronics Co., Ltd.
+ * Copyright (c) 2016 Samsung Electronics Co., Ltd.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
class Popup;
}
-class Button;
-
/**
- * @brief Popup contains content that can come into focus when activated, and out of focus when deactivated.
- *
- * Content:
- *
- * The content within a popup consists of:
- *
- * 1. Title
- * 2. Buttons
- * 3. Background/Frame (i.e. Scale-9 image)
- * 4. Custom Content (Actors)
- *
- * All of which are optional.
+ * @brief The Popup widget provides a configurable pop-up dialog with built-in layout of three main fields.
*
- * States:
+ * Fields:
+ * - Background Image
+ * - Title
+ * - Content
+ * - Footer
*
- * A popup can be in a number of states:
- *
- * 1. HIDE (invisible)
- * 2. SHOW (visible at normal size)
- * 3. SHOW_MAXIMIZED (visible occupying full parent size)
- * 4. Or custom defined.
- *
- * Transition Effects:
- *
- * A popup can use various custom transition effects, e.g.
- * Alpha fade, Scaling transition, position/rotation, shader effects.
+ * Please see the programming guide for a detailed description of the Popup including examples.
*
* Signals
* | %Signal Name | Method |
* |-------------------|------------------------------|
- * | touched-outside | @ref OutsideTouchedSignal() |
+ * | touchedOutside | @ref OutsideTouchedSignal() |
+ * | showing | @ref ShowingSignal() |
+ * | shown | @ref ShownSignal() |
+ * | hiding | @ref HidingSignal() |
* | hidden | @ref HiddenSignal() |
*/
class DALI_IMPORT_API Popup : public Control
public:
/**
- * @brief Current popup state.
+ * @brief The start and end property ranges for this control.
*/
- enum PopupState
+ enum PropertyRange
{
- POPUP_NONE, ///< Init status
- POPUP_HIDE, ///< Hidden (not visible)
- POPUP_SHOW, ///< Shown (visible in default size)
+ PROPERTY_START_INDEX = Control::CONTROL_PROPERTY_END_INDEX + 1,
+ PROPERTY_END_INDEX = PROPERTY_START_INDEX + 1000 ///< Reserve property indices
};
- typedef Signal< void () > TouchedOutsideSignalType; ///< Touched outside signal type.
- typedef Signal< void () > HiddenSignalType; ///< Hidden signal type.
+ /**
+ * @brief An enumeration of properties belonging to the Popup class.
+ */
+ struct Property
+ {
+ enum
+ {
+ TITLE = PROPERTY_START_INDEX, ///< name "title", type Property::Map
+ CONTENT, ///< name "content", type Property::Map
+ FOOTER, ///< name "footer", type Property::Map
+ DISPLAY_STATE, ///< name "displayState", type std::string
+ TOUCH_TRANSPARENT, ///< name "touchTransparent", type bool
+ TAIL_VISIBILITY, ///< name "tailVisibility", type bool
+ TAIL_POSITION, ///< name "tailPosition", type Vector3
+ CONTEXTUAL_MODE, ///< name "contextualMode", type std::string
+ ANIMATION_DURATION, ///< name "animationDuration", type float
+ ANIMATION_MODE, ///< name "animationMode", type std::string
+ ENTRY_ANIMATION, ///< name "entryAnimation", type Property::Map
+ EXIT_ANIMATION, ///< name "exitAnimation", type Property::Map
+ AUTO_HIDE_DELAY, ///< name "autoHideDelay", type int
+ BACKING_ENABLED, ///< name "backingEnabled", type bool
+ BACKING_COLOR, ///< name "backingColor", type Vector4
+ POPUP_BACKGROUND_IMAGE, ///< name "popupBackgroundImage", type std::string
+ POPUP_BACKGROUND_BORDER, ///< name "popupBackgroundBorder", type Rect< int >, Values are in the order: left, right, bottom, top
+ TAIL_UP_IMAGE, ///< name "tailUpImage", type std::string
+ TAIL_DOWN_IMAGE, ///< name "tailDownImage", type std::string
+ TAIL_LEFT_IMAGE, ///< name "tailLeftImage", type std::string
+ TAIL_RIGHT_IMAGE, ///< name "tailRightImage", type std::string
+ };
+ };
/**
- * @brief Signal emitted when user has touched outside of the Dialog.
+ * The display states of the Popup.
*/
- TouchedOutsideSignalType& OutsideTouchedSignal();
+ enum DisplayState
+ {
+ SHOWING, ///< The popup is transitioning in
+ SHOWN, ///< The popup is fully shown
+ HIDING, ///< The popup is transitioning out
+ HIDDEN ///< The popup is fully hidden
+ };
/**
- * @brief Signal emitted when popup has been hidden.
+ * The animation mode within popup.
+ * Choose from a predefined mode or "CUSTOM" to use the ANIMATION_IN and ANIMATION_OUT properties.
*/
- HiddenSignalType& HiddenSignal();
+ enum AnimationMode
+ {
+ NONE, ///< No animation.
+ ZOOM, ///< Popup zooms in and out animating the scale property.
+ FADE, ///< Popup fades in and out.
+ CUSTOM ///< Use the EntryAnimation and ExitAnimation animation properties.
+ };
+
+ /**
+ * Types of contextual layout.
+ * The Popup is positioned adjacent to it's parent in the direction specified by this mode.
+ * NON_CONTEXTUAL disables any contextual positioning.
+ */
+ enum ContextualMode
+ {
+ NON_CONTEXTUAL,
+ ABOVE,
+ RIGHT,
+ BELOW,
+ LEFT
+ };
public:
Popup();
/**
+ * @brief Create the Popup control.
+ *
+ * @return A handle to the Popup control.
+ */
+ static Popup New();
+
+ /**
+ * @brief Destructor
+ *
+ * This is non-virtual since derived Handle types must not contain data or virtual methods.
+ */
+ ~Popup();
+
+ /**
* @brief Copy constructor.
*
* Creates another handle that points to the same real object
Popup& operator=( const Popup& handle );
/**
- * @brief Destructor
- *
- * This is non-virtual since derived Handle types must not contain data or virtual methods.
- */
- ~Popup();
-
- /**
- * @brief Create the Poup control.
- *
- * @return A handle to the Popup control.
- */
- static Popup New();
-
- /**
* @brief Downcast an Object handle to Popup.
*
* If handle points to a Popup the
public:
/**
- * @brief Sets the background image for this Popup.
- *
- * The background is resized (stretched according to scale settings),
- * to the size of the Popup.
+ * @brief Sets a title for this Popup.
*
- * @param[in] image The Background ImageActor to cover background
+ * @param[in] titleActor Any actor can be specified when using this method.
*/
- void SetBackgroundImage( Actor image );
+ void SetTitle( Actor titleActor );
/**
- * @brief Sets a title for this Popup.
+ * @brief Gets the title actor for this Popup.
*
- * By default a TextView is created with following settings: black color, split-by-word multi-line policy and split exceed policy.
- *
- * @param[in] text The text to appear as the heading for this Popup
+ * @return The actor representing the title is returned.
*/
- void SetTitle( const std::string& text );
+ Actor GetTitle() const;
/**
- * @brief Gets the text (TextView) for this Popup.
+ * @brief Sets the content actor.
+ * This can any actor type or heirarchy of actors.
*
- * @return The text to appear as the heading for this Popup
+ * @param[in] content The actor to use.
*/
- std::string GetTitle() const;
+ void SetContent( Actor content );
/**
- * @brief Adds a button to this Popup.
+ * @brief Gets the actor currently used for the content.
*
- * Buttons are added to the bottom of the Popup and Centered.
+ * @return The content actor.
+ */
+ Actor GetContent() const;
+
+ /**
+ * @brief Sets the actor to use for a footer in this Popup.
*
- * By default the first button added will have the focus, and the focus will
- * shift to other buttons based on the sequence in which they are added to the popup.
+ * @param[in] footer The footer actor to be added to this Popup
+ */
+ void SetFooter( Actor footer );
+
+ /**
+ * @brief Gets the footer actor.
*
- * @param[in] button The button to be added to this Popup
+ * @return The footer actor.
*/
- void AddButton( Button button );
+ Actor GetFooter() const;
/**
- * @brief Sets state of Popup, such as HIDE, and SHOW.
+ * @brief Sets the display state of Popup.
+ *
+ * There are 4 total display states.
+ * Only 2 can be set, but all four can be read for better inspection of the current popup state.
+ *
+ * The other two states are getable, but not setable and are there for consistency.
*
- * The Popup will instantaneously jump to this state.
+ * | Value | Setting the state | Getting the state |
+ * |----------|--------------------------------|--------------------------------|
+ * | SHOWN | Show the popup | The popup is fully shown |
+ * | HIDDEN | Hide the popup | The popup is fully hidden |
+ * | SHOWING | | The popup is transitioning in |
+ * | HIDING | | The popup is transitioning out |
*
- * @param[in] state The state of the popup
+ * All 4 state changes cause notifications via 4 respective signals that can be connected to.
+ * @see GetDisplayState()
+ *
+ * @param[in] displayState The desired display state to change to.
*/
- void SetState( PopupState state );
+ void SetDisplayState( Toolkit::Popup::DisplayState displayState );
/**
- * @brief Sets state of Popup, such as HIDE, and SHOW.
+ * @brief Gets the current state of the popup.
*
- * The Popup will smoothly animate to this state.
+ * This will also show if the popup is in the process of showing or hiding.
*
- * @param[in] state The state of the popup
- * @param[in] duration The time to animate to this new state.
+ * @return The current state of the popup.
*/
- void SetState( PopupState state, float duration );
+ Toolkit::Popup::DisplayState GetDisplayState() const;
+
+public:
+
+ typedef Signal< void () > TouchedOutsideSignalType; ///< Touched outside signal type.
+ typedef Signal< void () > DisplayStateChangeSignalType; ///< Used for signals emitted when the displayed state changes.
/**
- * @brief Gets the state of the popup.
- *
- * @return The state of the popup.
+ * @brief Signal emitted when user has touched outside of the Dialog.
*/
- PopupState GetState() const;
+ TouchedOutsideSignalType& OutsideTouchedSignal();
/**
- * @brief Shows the popup.
- *
- * The Popup will animate to the SHOW state
+ * @brief Signal emitted when the Popup is starting to be shown.
*/
- void Show();
+ DisplayStateChangeSignalType& ShowingSignal();
/**
- * @brief Hides the popup.
- *
- * The Popup will animate to the HIDE state
+ * @brief Signal emitted when the Popup has been fully displayed.
*/
- void Hide();
+ DisplayStateChangeSignalType& ShownSignal();
/**
- * @brief Shows the tail.
- *
- * The tail position is specified relative to it's Parent.
- * To display at top center for instace, pass:
- *
- * ParentOrigin::TOP_CENTER
- *
- * @note The tail images are defined inside PopupStyle as
- * tailUpImage, tailDownImage, tailLeftImage, and tailRightImage
- *
- * @param[in] position A position around the perimeter of the Parent.
+ * @brief Signal emitted when the Popup is starting to be hidden.
*/
- void ShowTail(const Vector3& position);
+ DisplayStateChangeSignalType& HidingSignal();
/**
- * @brief Hides the tail.
+ * @brief Signal emitted when the Popup has been completely hidden.
*/
- void HideTail();
+ DisplayStateChangeSignalType& HiddenSignal();
public: // Not intended for application developers
*
* @param[in] implementation The Control implementation.
*/
- DALI_INTERNAL Popup(Internal::Popup& implementation);
+ DALI_INTERNAL Popup( Internal::Popup& implementation );
/**
* @brief Allows the creation of this Control from an Internal::CustomActor pointer.
projects / platform / core / uifw / dali-toolkit.git / blobdiff