dali-toolkit/internal/controls/tooltip/tooltip.h

   1 #ifndef DALI_INTERNAL_TOOLTIP_H
   2 #define DALI_INTERNAL_TOOLTIP_H
   3
   4 /*
   5  * Copyright (c) 2017 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 // EXTERNAL INCLUDES
  22 #include <string>
  23 #include <dali/public-api/adaptor-framework/timer.h>
  24 #include <dali/public-api/common/intrusive-ptr.h>
  25 #include <dali/public-api/object/property-array.h>
  26 #include <dali/public-api/object/property-map.h>
  27 #include <dali/public-api/object/ref-object.h>
  28 #include <dali/public-api/signals/connection-tracker.h>
  29 #include <dali/public-api/object/weak-handle.h>
  30
  31 // INTERNAL INCLUDES
  32 #include <dali-toolkit/public-api/controls/control.h>
  33 #include <dali-toolkit/devel-api/controls/popup/popup.h>
  34 #include <dali-toolkit/devel-api/controls/tooltip/tooltip-properties.h>
  35
  36 namespace Dali
  37 {
  38
  39 namespace Toolkit
  40 {
  41
  42 namespace Internal
  43 {
  44
  45 class Tooltip;
  46 typedef IntrusivePtr< Tooltip > TooltipPtr;
  47
  48 /**
  49  * @brief Handles all the required tooltip related functionality for a control.
  50  *
  51  * Connects to the Hovered signal of the control.
  52  * Styling is achieved by merging the properties set so that new properties override previous but existing properties are still kept.
  53  */
  54 class Tooltip : public RefObject, public ConnectionTracker
  55 {
  56 public:
  57
  58   /**
  59    * @brief Creates an instance of the Tooltip class.
  60    * @param[in]  control  The control the tooltip should be shown on.
  61    */
  62   static TooltipPtr New( Toolkit::Control control );
  63
  64   /**
  65    * @brief Sets the properties of the Tooltip.
  66    * @details The properties are merged over the currently stored properties.
  67    *          If a Property::STRING is passed, then the style set previously by the stylesheet is used.
  68    *          If a Property::MAP then the map is merged.
  69    *          If a Property::ARRAY of Visuals then all are displayed in one row.
  70    * @param[in]  value  This can either be a Property::STRING, Property::MAP or Property::ARRAY.
  71    */
  72   void SetProperties( const Property::Value& value );
  73
  74   /**
  75    * @brief Creates a property map of the tooltip properties.
  76    * @param[out]  map  Filled with all the properties of the tooltip.
  77    * @note map should be empty.
  78    */
  79   void CreatePropertyMap( Property::Map& map ) const;
  80
  81 private:
  82
  83   /**
  84    * @brief Private constructor.
  85    */
  86   Tooltip( Toolkit::Control control );
  87
  88   /**
  89    * @brief Private destructor.
  90    */
  91   ~Tooltip();
  92
  93   Tooltip( const Tooltip& ); ///< Undefined
  94   Tooltip& operator=( const Tooltip& ); ///< ///< Undefined
  95
  96   /**
  97    * @brief Sets the content of the tooltip.
  98    * @details Connects to the signals if there is real content to display.
  99    * @param[in]  control  Is used to connect to this control's signals.
 100    * @param[in]  value    The content property value.
 101    */
 102   void SetContent( Toolkit::Control& control, const Property::Value& value );
 103
 104   /**
 105    * @brief Sets the background properties of the tooltip.
 106    * @param[in]  value  The background property value.
 107    */
 108   void SetBackground( const Property::Value& value );
 109
 110   /**
 111    * @brief Sets the tail properties of the tooltip.
 112    * @param[in]  value  The tail property value.
 113    */
 114   void SetTail( const Property::Value& value );
 115
 116   /**
 117    * @brief Method used to connect to the control's Hovered signal.
 118    * @param[in]  hover  The hover event.
 119    */
 120   bool OnHovered( Actor /* actor */, const HoverEvent& hover );
 121
 122   /**
 123    * @brief Method used to connect to the internal timer used by Tooltip.
 124    * @return Always return false as we're only interested in one timeout.
 125    */
 126   bool OnTimeout();
 127
 128   /**
 129    * @brief Used to know when the we're laying out the actor used to display the tooltip.
 130    * @details This is required so we can appropriately position it.
 131    * @param[in]  actor  The actor being laid out.
 132    */
 133   void OnRelayout( Actor actor );
 134
 135   // Data
 136
 137   Toolkit::Popup mPopup; ///< The Popup class is used to display the actual tooltip.
 138   Timer mTooltipTimer; ///< Timer used to wait a certain length of time before we display the tooltip.
 139
 140   WeakHandle< Toolkit::Control > mControl; ///< A weak handle to the control we are setting the tooltip on.
 141
 142   Property::Map mContentTextVisual; ///< If using just one visual, then this is set.
 143   Property::Map mTailImages; ///< The different images used by the tail.
 144   Property::Array mContentArray; ///< If using an array of visuals, then this is used.
 145
 146   Rect< int > mBackgroundBorder; ///< The size of the background border in the order: left, right, bottom, top. @see Toolkit::Tooltip::Border::Property::BORDER
 147
 148   Vector2 mLayout; ///< The layout of the content if using an array.
 149   Vector2 mHoverPoint; ///< The first point where hover starts.
 150   Vector2 mHoverPointOffset; ///< The tooltip is displayed with this offset from hover point if using Toolkit::Tooltip::Position::HOVER_POINT.
 151
 152   std::string mBackgroundImage; ///< The path to the background image used for the tooltip.
 153
 154   float mMovementThreshold; ///< This is the allowable movement of the hover before the tooltip processing is cancelled.
 155
 156   int mWaitTime; ///< Time in milliseconds to wait before we display the tooltip.
 157
 158   Toolkit::Tooltip::Position::Type mPositionType; ///< The position of the tooltip.
 159   bool mTailVisibility; ///< Whether we are showing a tail or not.
 160   bool mDisappearOnMovement; ///< Whether the tooltip is set to disappear on movement or when we go out of the bounds of mControl.
 161   bool mSignalsConnected; ///< Whether any signals required for Tooltip functionality have been connected.
 162 };
 163
 164 } // namespace Internal
 165
 166 } // namespace Toolkit
 167
 168 } // namespace Dali
 169
 170 #endif // DALI_INTERNAL_TOOLTIP_H