Fixed crash when Visual model positions < glyphs
[platform/core/uifw/dali-toolkit.git] / dali-toolkit / internal / text / visual-model.h
1 #ifndef __DALI_TOOLKIT_TEXT_VISUAL_MODEL_H__
2 #define __DALI_TOOLKIT_TEXT_VISUAL_MODEL_H__
3
4 /*
5  * Copyright (c) 2015 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/public-api/common/intrusive-ptr.h>
23 #include <dali/public-api/object/ref-object.h>
24 #include <dali-toolkit/internal/text/text-definitions.h>
25
26 namespace Dali
27 {
28
29 struct Vector2;
30
31 namespace Toolkit
32 {
33
34 namespace Text
35 {
36
37 struct LineRun;
38 class VisualModel;
39 typedef IntrusivePtr<VisualModel> VisualModelPtr;
40
41 /**
42  * @brief A visual text model contains layout specific information.
43  *
44  * This includes:
45  * - A series of glyphs in visual order i.e. after the bidirectional reordering.
46  * - The position of each glyph within a 2D bounding box.
47  */
48 class VisualModel : public RefObject
49 {
50 public:
51
52   /**
53    * @brief Create a new instance of a VisualModel.
54    *
55    * @return A pointer to a new VisualModel.
56    */
57   static VisualModelPtr New();
58
59   // Glyph interface.
60
61   /**
62    * @brief Replaces any glyphs previously set.
63    *
64    * @param[in] glyphs An array of glyphs in the visual order.
65    * @param[in] characterIndices An array containing the first character in the logical model that each glyph relates to.
66    * @param[in] charactersPerGlyph An array containing the number of characters per glyph.
67    * @param[in] numberOfGlyphs The number of glyphs.
68    */
69   void SetGlyphs( const GlyphInfo* glyphs,
70                   const CharacterIndex* characterIndices,
71                   const Length* charactersPerGlyph,
72                   Length numberOfGlyphs );
73
74   /**
75    * Retrieves the number of glyphs.
76    *
77    * @return The number of glyphs.
78    */
79   Length GetNumberOfGlyphs() const;
80
81   /**
82    * @brief Retrieves glyphs in the given buffer.
83    *
84    * The size of the @p glyphs buffer needs to be big enough to copy the @p numberOfGlyphs.
85    * @param[out] glyphs Pointer to a buffer where the glyphs are copied.
86    * @param[in] glyphIndex Index to the first glyph.
87    * @param[in] numberOfGlyphs Number of glyphs to be copied.
88    */
89   void GetGlyphs( GlyphInfo* glyphs,
90                   GlyphIndex glyphIndex,
91                   Length numberOfGlyphs ) const;
92
93   /**
94    * Retrieves a glyph.
95    *
96    * @param[in] glyphIndex Index to a glyph.
97    *
98    * @return A glyph.
99    */
100   const GlyphInfo& GetGlyphInfo( GlyphIndex glyphIndex ) const;
101
102   // Character <--> Glyph conversion
103
104   /**
105    * @brief Retrieves the first character in the logical model which a glyph represents.
106    *
107    * @note After shaping several characters may be represented by the same glyph.
108    * Alternatively several glyphs may be required to display a character.
109    * @param[in] glyphIndex The glyph index.
110    * @return The character index.
111    */
112   CharacterIndex GetCharacterIndex( GlyphIndex glyphIndex ) const;
113
114   /**
115    * @brief Query the number of characters the glyph represents.
116    *
117    * @param[in] glyphIndex The glyph index.
118    * @return The number of characters represented by the glyph.
119    */
120   Length GetCharactersPerGlyph( GlyphIndex glyphIndex ) const;
121
122   /**
123    * Retrieves the first glyph in the visual model which represents a given character.
124    *
125    * @note After shaping several characters may be represented by the same glyph.
126    * Alternatively several glyphs may be required to display a character.
127    * @param[in] characterIndex The character index.
128    * @return The glyph index.
129    */
130   GlyphIndex GetGlyphIndex( CharacterIndex characterIndex ) const;
131
132   /**
133    * Retrieves the whole or part of the character to glyph conversion map.
134    *
135    * The size of the buffer needs to be big enough to copy the @p numberOfCharacters.
136    *
137    * @param[out] characterToGlyphMap Pointer to a buffer where the conversion map is copied.
138    * @param[in] characterIndex Index to the first character.
139    * @param[in] numberOfCharacters The number of characters.
140    */
141   void GetCharacterToGlyphMap( GlyphIndex* characterToGlyphMap,
142                                CharacterIndex characterIndex,
143                                Length numberOfCharacters ) const;
144
145   /**
146    * Retrieves for each glyph the number of characters the glyph represents.
147    *
148    * @param[out] charactersPerGlyph Pointer to a buffer where the number of characters for each glyph are copied.
149    * @param[in] glyphIndex Index to the first glyph.
150    * @param[in] numberOfGlyphs The number of glyphs.
151    */
152   void GetCharactersPerGlyphMap( Length* charactersPerGlyph,
153                                  GlyphIndex glyphIndex,
154                                  Length numberOfGlyphs ) const;
155
156   /**
157    * Retrieves the whole or part of the glyph to character conversion map.
158    *
159    * The size of the buffer needs to be big enough to copy the @p numberOfGlyphs.
160    *
161    * @param[out] glyphToCharacter Pointer to a buffer where the conversion map is copied.
162    * @param[in] glyphIndex Index to the first glyph.
163    * @param[in] numberOfGlyphs The number of glyphs.
164    */
165   void GetGlyphToCharacterMap( CharacterIndex* glyphToCharacter,
166                                GlyphIndex glyphIndex,
167                                Length numberOfGlyphs ) const;
168
169   // Position interface
170
171   /**
172    * @brief Replaces any glyph positions previously set.
173    *
174    * @param[in] glyphPositions An array of visual positions for each glyph.
175    * @param[in] numberOfGlyphs The number of positions.
176    */
177   void SetGlyphPositions( const Vector2* glyphPositions,
178                           Length numberOfGlyphs );
179
180   /**
181    * Retrieves the number of glyph positions set.
182    *
183    * @note This may be less than the number of glyphs in the model.
184    * @return The number of glyphs.
185    */
186   Length GetNumberOfGlyphPositions() const;
187
188   /**
189    * @brief Retrieves the glyph positions.
190    *
191    * @pre The size of the @p positions buffer needs to be big enough to copy the @p numberOfGlyphs positions.
192    * @param[out] glyphPositions Pointer to a buffer where the glyph positions are copied.
193    * @param[in] glyphIndex Index to the first glyph position.
194    * @param[in] numberOfGlyphs The number of positions to be copied.
195    */
196   void GetGlyphPositions( Vector2* glyphPositions,
197                           GlyphIndex glyphIndex,
198                           Length numberOfGlyphs ) const;
199
200   /**
201    * Retrieve the glyph's position of the given glyph.
202    *
203    * @param[in] glyphIndex Index to the glyph.
204    *
205    * @return The glyph's position.
206    */
207   const Vector2& GetGlyphPosition( GlyphIndex glyphIndex ) const;
208
209   // Line interface.
210
211   /**
212    * Sets the lines.
213    *
214    * Replaces any lines previously set.
215    *
216    * Every line is an item run containing the index to the first glyph of the line and the number of glyphs.
217    *
218    * @param[in] lines Pointer to a buffer containing all the line runs.
219    * @param[in] numberOfLines The number of lines in the buffer.
220    */
221   void SetLines( const LineRun* const lines,
222                  Length numberOfLines );
223
224   /**
225    * Retrieves the number of lines of the whole text.
226    *
227    * @return The number of lines.
228    */
229   Length GetNumberOfLines() const;
230
231   /**
232    * Retrieves lines.
233    *
234    * The size of the @p lines buffer needs to be big enough to copy the @p numberOfLines.
235    *
236    * @param[out] lines Pointer to a buffer where the lines are copied.
237    * @param[in] lineIndex Index to the first line.
238    * @param[in] numberOfLines Number of lines to be copied.
239    */
240   void GetLines( LineRun* lines,
241                  LineIndex lineIndex,
242                  Length numberOfLines ) const;
243
244   /**
245    * Retrieves the number of lines where the given range of glyphs is laid out.
246    *
247    * @param[in] glyphIndex Index to the first glyph.
248    * @param[in] numberOfGlyphs The number of glyph.
249    *
250    * @return The number of lines.
251    */
252   TextAbstraction::Length GetNumberOfLines( GlyphIndex glyphIndex,
253                                             Length numberOfGlyphs ) const;
254   /**
255    * Retrieves the lines where the given range of glyphs is laid out.
256    *
257    * The size of the @p lines buffer needs to be big enough to copy the @p numberOfLines.
258    *
259    * @param[out] lines Pointer to a buffer where the lines are copied.
260    * @param[in] glyphIndex Index to the first glyphs of the range.
261    * @param[in] numberOfGlyphs Number of glyphs in the range.
262    */
263   void GetLinesOfGlyphRange( LineRun* lines,
264                              GlyphIndex glyphIndex,
265                              Length numberOfGlyphs ) const;
266
267   // Size interface
268
269   /**
270    * Sets the natural size.
271    *
272    * @param[in] size The text's natural size.
273    */
274   void SetNaturalSize( const Vector2& size  );
275
276   /**
277    * Retrieves the natural size.
278    *
279    * @return The text's natural size.
280    */
281   const Vector2& GetNaturalSize() const;
282
283   /**
284    * Sets the text's actual size after it has been laid out.
285    *
286    * @param[in] size The text's size.
287    */
288   void SetActualSize( const Vector2& size );
289
290   /**
291    * Retrieves the text's actual size after it has been laid out.
292    *
293    * @return The text's size.
294    */
295   const Vector2& GetActualSize() const;
296
297 protected:
298
299   /**
300    * @brief A reference counted object may only be deleted by calling Unreference().
301    */
302   virtual ~VisualModel();
303
304 private:
305
306   /**
307    * @brief Private constructor.
308    */
309   VisualModel();
310
311   // Undefined
312   VisualModel( const VisualModel& handle );
313
314   // Undefined
315   VisualModel& operator=( const VisualModel& handle );
316
317 private:
318
319   struct Impl;
320   Impl* mImpl;
321 };
322 } // namespace Text
323
324 } // namespace Toolkit
325
326 } // namespace Dali
327
328 #endif // __DALI_TOOLKIT_TEXT_VISUAL_MODEL_H__