X-Git-Url: http://review.tizen.org/git/?p=platform%2Fcore%2Fuifw%2Fdali-toolkit.git;a=blobdiff_plain;f=dali-toolkit%2Fdevel-api%2Fcontrols%2Fpopup%2Fpopup.h;h=3d3d9152e6d7c49fd8182735092e42966389a4a9;hp=32322e2025e0bd25c1d0668f47866f6071b271a8;hb=4107c0f5ea45cd9e4e61d30c30e99de0e00287fc;hpb=f58b8383147de70affa1e3949cf1c6757d705d3c diff --git a/dali-toolkit/devel-api/controls/popup/popup.h b/dali-toolkit/devel-api/controls/popup/popup.h index 32322e2..3d3d915 100644 --- a/dali-toolkit/devel-api/controls/popup/popup.h +++ b/dali-toolkit/devel-api/controls/popup/popup.h @@ -2,7 +2,7 @@ #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. @@ -32,40 +32,24 @@ namespace Internal DALI_INTERNAL 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 @@ -74,27 +58,81 @@ 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: @@ -104,6 +142,20 @@ 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 @@ -121,20 +173,6 @@ public: 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 @@ -147,102 +185,108 @@ public: 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 @@ -251,7 +295,7 @@ 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.