dali-toolkit/devel-api/controls/tooltip/tooltip-properties.h

   1 #ifndef DALI_TOOLKIT_TOOLTIP_PROPERTIES_H
   2 #define DALI_TOOLKIT_TOOLTIP_PROPERTIES_H
   3
   4 /*
   5  * Copyright (c) 2020 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/object/property-index-ranges.h>
  23
  24 namespace Dali
  25 {
  26 namespace Toolkit
  27 {
  28 namespace Tooltip
  29 {
  30 /**
  31  * @brief The properties used for a Tooltip.
  32  */
  33 namespace Property
  34 {
  35 enum
  36 {
  37   /**
  38    * @brief The content to display.
  39    * @details Name "content", type Property::STRING, Property::MAP or Property::ARRAY.
  40    *          If Property::STRING is used, then the string is shown as a text and the default font style for a Tooltip will be used.
  41    *          This can be overridden by passing in a Property::MAP of TextVisual properties. For text styling purposes, a Property::MAP excluding the TEXT property can be sent.
  42    *          If a different Visual is required, then a Property::MAP defining that visual can be set.
  43    *          If more than one visual is required, then a Property::ARRAY can be used. The contents are added to the layout as per their order in the array. Text has to be styled in the visual passed in (default toolkit style will not be used).
  44    * @note Mandatory.
  45    * @note If set using Property::STRING, then when retrieved, a Property::MAP is returned.
  46    *       If set using a Property::MAP or Property::ARRAY, then the appropriate type is returned.
  47    * @see Toolkit::TextVisual
  48    */
  49   CONTENT = CORE_PROPERTY_MAX_INDEX + 1,
  50
  51   /**
  52    * @brief The layout of the content.
  53    * @details Name "layout", type Property::VECTOR2.
  54    *          The number of rows and columns expected.
  55    *          ( 1, 2 ) means 1 row, 2 columns so the content will have two items placed on one row.
  56    *          ( 2, 2 ) means 2 rows, 2 columns so the content will have 4 items with two items placed on each row.
  57    * @note Optional.
  58    * @note If not provided, the default is to put all items in the same row.
  59    */
  60   LAYOUT,
  61
  62   /**
  63    * @brief Time to wait in seconds before a tooltip is shown while the is movement is within the allowed threshold.
  64    * @details Name "waitTime", type Property::FLOAT.
  65    * @note Optional.
  66    * @note If not provided, the default is 0.5 seconds.
  67    */
  68   WAIT_TIME,
  69
  70   /**
  71    * @brief The background of the tooltip.
  72    * @details Name "background", type Property::STRING or Property::MAP.
  73    *          If Property::STRING, then the path to the image is required and it's assumed that there are no borders.
  74    * @note Optional.
  75    * @note If not provided, the default is taken from the stylesheet.
  76    * @note When retrieved, a Property::MAP is returned.
  77    * @see Tooltip::Background
  78    */
  79   BACKGROUND,
  80
  81   /**
  82    * @brief The tail used by the tooltip.
  83    * @details Name "tail", type Property::BOOLEAN or Property::MAP.
  84    *          If Property::BOOLEAN and true, then the default visuals are used for the tail.
  85    *          A Property::MAP can be used to override the visuals for the tail.
  86    * @note Optional.
  87    * @note The default is false, i.e. to not show a tail.
  88    * @note When retrieved, a Property::MAP is returned.
  89    * @note If the popup has to be moved because it goes out of bounds, then the tail is not shown regardless of whether it is set or not.
  90    * @see Tooltip::Tail
  91    */
  92   TAIL,
  93
  94   /**
  95    * @brief The position of the tooltip in relation to the control.
  96    * @details Name "position", type Tooltip::Position::Type (Property::INTEGER) or Property::STRING.
  97    * @note Optional.
  98    * @note If not provided, the default is Tooltip::Position::BELOW.
  99    * @note When retrieved, a Tooltip::Position::Type (Property::INTEGER) is returned.
 100    */
 101   POSITION,
 102
 103   /**
 104    * @brief If Tooltip::Position::HOVER_POINT is used for the POSITION, then this is the offset the tooltip is displayed at from the hover point.
 105    * @details Name "hoverPointOffset", type Property::VECTOR2.
 106    * @note Optional.
 107    * @note If not provided, the default is Vector2( 10.0f, 10.0f ).
 108    */
 109   HOVER_POINT_OFFSET,
 110
 111   /**
 112    * @brief The movement threshold allowed before showing (or hiding a popup).
 113    * @details Name "movementThreshold", type Property::INTEGER.
 114    *          This value is used as the threshold to hide the popup as well if DISAPPEAR_ON_MOVEMENT is set to true.
 115    * @note Optional.
 116    * @note If not provided, the default is 5.
 117    */
 118   MOVEMENT_THRESHOLD,
 119
 120   /**
 121    * @brief If true, the tooltip will disappear after hover movement beyond a certain distance.
 122    * @details Name "disappearOnMovement", type Property::BOOLEAN.
 123    * @note Optional.
 124    * @note If not provided, the default is to disappear only when moving out of bounds of the control.
 125    */
 126   DISAPPEAR_ON_MOVEMENT,
 127 };
 128
 129 } // namespace Property
 130
 131 namespace Background
 132 {
 133 namespace Property
 134 {
 135 enum
 136 {
 137   /**
 138    * @brief The image to use as the background.
 139    * @details Name "visual", type Property::STRING.
 140    */
 141   VISUAL,
 142
 143   /**
 144    * @brief The size of the borders in the order: left, right, bottom, top.
 145    * @details Name "border", type Property::RECTANGLE.
 146    *          This is different from the nPatch border as the it will place the content within the bounds specified.
 147    *          For example, there could be some round corners in the image used and we may not want the content going over the rounded corners.
 148    * @note Optional.
 149    * @note If not provided, then then it is assumed that the image does not have a border.
 150    */
 151   BORDER
 152 };
 153
 154 } // namespace Property
 155
 156 } // namespace Background
 157
 158 /**
 159  * @brief The tail used by the tooltip.
 160  */
 161 namespace Tail
 162 {
 163 /**
 164  * @brief The properties of the tail used by the tooltip.
 165  */
 166 namespace Property
 167 {
 168 enum
 169 {
 170   /**
 171    * @brief Whether to show the tail or not.
 172    * @details Name "visibility", type Property::BOOLEAN.
 173    * @note Optional.
 174    * @note If the popup has to be moved because it goes out of bounds, then the tail is not shown regardless of whether it is set or not.
 175    */
 176   VISIBILITY,
 177
 178   /**
 179    * @brief The image used for the tail if it is above the tooltip.
 180    * @details Name "aboveVisual", type Property::STRING.
 181    */
 182   ABOVE_VISUAL,
 183
 184   /**
 185    * @brief The image used for the tail if it is below the tooltip.
 186    * @details Name "belowVisual", type Property::STRING.
 187    */
 188   BELOW_VISUAL
 189 };
 190
 191 } // namespace Property
 192
 193 } // namespace Tail
 194
 195 namespace Position
 196 {
 197 /**
 198  * @brief The position of the tooltip in relation to the control.
 199  */
 200 enum Type
 201 {
 202   ABOVE,      ///< The tooltip will appear above the control.
 203   BELOW,      ///< The tooltip will appear below the control.
 204   HOVER_POINT ///< The tooltip will appear near the hover point.
 205 };
 206
 207 } // namespace Position
 208
 209 } // namespace Tooltip
 210
 211 } // namespace Toolkit
 212
 213 } // namespace Dali
 214
 215 #endif // DALI_TOOLKIT_TOOLTIP_PROPERTIES_H