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