dali-toolkit/internal/text/cursor-helper-functions.h

   1 #ifndef DALI_TOOLKIT_TEXT_CURSOR_HELPER_FUNCTIONS_H
   2 #define DALI_TOOLKIT_TEXT_CURSOR_HELPER_FUNCTIONS_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 // INTERNAL INCLUDES
  22 #include <dali-toolkit/internal/text/logical-model-impl.h>
  23 #include <dali-toolkit/internal/text/metrics.h>
  24 #include <dali-toolkit/internal/text/visual-model-impl.h>
  25 #include <dali-toolkit/internal/text/glyph-metrics-helper.h>
  26
  27 namespace Dali
  28 {
  29 namespace Toolkit
  30 {
  31 namespace Text
  32 {
  33 struct CharacterHitTest
  34 {
  35   /**
  36    * @brief Enumeration of the types of hit test.
  37    */
  38   enum Mode
  39   {
  40     TAP,   ///< Retrieves the first or last character of the line if the touch point is outside of the boundaries of the text.
  41     SCROLL ///< Retrieves the character above or below to the touch point if it's outside of the boundaries of the text.
  42   };
  43 };
  44
  45 struct CursorInfo
  46 {
  47   CursorInfo()
  48   : primaryPosition(),
  49     secondaryPosition(),
  50     lineOffset(0.f),
  51     glyphOffset(0.f),
  52     lineHeight(0.f),
  53     primaryCursorHeight(0.f),
  54     secondaryCursorHeight(0.f),
  55     isSecondaryCursor(false)
  56   {
  57   }
  58
  59   ~CursorInfo()
  60   {
  61   }
  62
  63   Vector2 primaryPosition;       ///< The primary cursor's position (in text's coords).
  64   Vector2 secondaryPosition;     ///< The secondary cursor's position (in text's coords).
  65   float   lineOffset;            ///< The vertical offset where the line containing the cursor starts.
  66   float   glyphOffset;           ///< The difference of line ascender and glyph ascender.
  67   float   lineHeight;            ///< The height of the line where the cursor is placed.
  68   float   primaryCursorHeight;   ///< The primary cursor's height.
  69   float   secondaryCursorHeight; ///< The secondary cursor's height.
  70   bool    isSecondaryCursor;     ///< Whether the secondary cursor is valid.
  71 };
  72
  73 /**
  74  * @brief Parameters passed to the GetCursorPosition() function.
  75  */
  76 struct GetCursorPositionParameters
  77 {
  78   VisualModelPtr  visualModel;  ///< The visual model.
  79   LogicalModelPtr logicalModel; ///< The logical model.
  80   MetricsPtr      metrics;      ///< A wrapper around FontClient used to get metrics.
  81   CharacterIndex  logical;      ///< The logical cursor position (in characters). 0 is just before the first character, a value equal to the number of characters is just after the last character.
  82   bool            isMultiline;  ///< Whether the text control is multi-line.
  83 };
  84
  85 /**
  86  * @brief Retrieves the closest line for a given touch point.
  87  *
  88  * It returns the first line if the touch point is above the text and the last line if the touch point is below.
  89  *
  90  * @param[in] visualModel The visual model.
  91  * @param[in] visualY The touch point 'y' in text's coords.
  92  * @param[out] matchedLine Whether the touch point actually hits a line.
  93  *
  94  * @return A line index.
  95  */
  96 LineIndex GetClosestLine(VisualModelPtr visualModel,
  97                          float          visualY,
  98                          bool&          matchedLine);
  99
 100 /**
 101  * @brief Calculates the vertical line's offset for a given line.
 102  *
 103  * @pre @p lineIndex must be between 0 and the number of lines (both inclusive).
 104  *
 105  * @param[in] lines The laid-out lines.
 106  * @param[in] lineIndex Index to the line.
 107  *
 108  * @return The vertical offset of the given line.
 109  */
 110 float CalculateLineOffset(const Vector<LineRun>& lines,
 111                           LineIndex              lineIndex);
 112
 113 /**
 114  * @brief Retrieves the cursor's logical position for a given touch point x,y
 115  *
 116  * There are two types of hit test: CharacterHitTest::TAP retrieves the first or
 117  * last character of a line if the touch point is outside the boundaries of the
 118  * text, CharacterHitTest::SCROLL retrieves the character above or below to the
 119  * touch point if it's outside the boundaries of the text.
 120  *
 121  * @param[in] visualModel The visual model.
 122  * @param[in] logicalModel The logical model.
 123  * @param[in] metrics A wrapper around FontClient used to get metrics.
 124  * @param[in] visualX The touch point 'x' in text's coords.
 125  * @param[in] visualY The touch point 'y' in text's coords.
 126  * @param[in] mode The type of hit test.
 127  * @param[out] matchedCharacter Whether the touch point actually hits a character.
 128  *
 129  * @return The logical cursor position (in characters). 0 is just before the first character, a value equal to the number of characters is just after the last character.
 130  */
 131 CharacterIndex GetClosestCursorIndex(VisualModelPtr         visualModel,
 132                                      LogicalModelPtr        logicalModel,
 133                                      MetricsPtr             metrics,
 134                                      float                  visualX,
 135                                      float                  visualY,
 136                                      CharacterHitTest::Mode mode,
 137                                      bool&                  matchedCharacter);
 138
 139 /**
 140  * @brief Calculates the cursor's position for a given character index in the logical order.
 141  *
 142  * It retrieves as well the line's height and the cursor's height and
 143  * if there is a valid alternative cursor, its position and height.
 144  *
 145  * @param[in] parameters Parameters used to calculate the cursor's position.
 146  * @param[in] defaultFontLineHeight The default font line height.
 147  * @param[out] cursorInfo The line's height, the cursor's height, the cursor's position and whether there is an alternative cursor.
 148  */
 149 void GetCursorPosition(GetCursorPositionParameters& parameters,
 150                        float                        defaultFontLineHeight,
 151                        CursorInfo&                  cursorInfo);
 152
 153 /**
 154  * @brief Find the indices to the first and last characters of a word for the given touch point.
 155  *
 156  * @param[in] visualModel The visual model.
 157  * @param[in] logicalModel The logical model.
 158  * @param[in] metrics A wrapper around FontClient used to get metrics.
 159  * @param[in] visualX The touch point 'x' in text's coords.
 160  * @param[in] visualY The touch point 'y' in text's coords.
 161  * @param[out] startIndex Index to the first character of the selected word.
 162  * @param[out] endIndex Index to the last character of the selected word.
 163  * @param[out] noTextHitIndex Index to the nearest character when there is no hit.
 164  *
 165  * @return @e true if the touch point hits a character.
 166  */
 167 bool FindSelectionIndices(VisualModelPtr  visualModel,
 168                           LogicalModelPtr logicalModel,
 169                           MetricsPtr      metrics,
 170                           float           visualX,
 171                           float           visualY,
 172                           CharacterIndex& startIndex,
 173                           CharacterIndex& endIndex,
 174                           CharacterIndex& noTextHitIndex);
 175
 176 } // namespace Text
 177
 178 } // namespace Toolkit
 179
 180 } // namespace Dali
 181
 182 #endif // DALI_TOOLKIT_TEXT_CURSOR_HELPER_FUNCTIONS_H