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

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