MezzanineEngine 
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
textline.h
1 //© Copyright 2010 - 2012 BlackTopp Studios Inc.
2 /* This file is part of The Mezzanine Engine.
3 
4  The Mezzanine Engine is free software: you can redistribute it and/or modify
5  it under the terms of the GNU General Public License as published by
6  the Free Software Foundation, either version 3 of the License, or
7  (at your option) any later version.
8 
9  The Mezzanine Engine is distributed in the hope that it will be useful,
10  but WITHOUT ANY WARRANTY; without even the implied warranty of
11  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12  GNU General Public License for more details.
13 
14  You should have received a copy of the GNU General Public License
15  along with The Mezzanine Engine. If not, see <http://www.gnu.org/licenses/>.
16 */
17 /* The original authors have included a copy of the license specified above in the
18  'Docs' folder. See 'gpl.txt'
19 */
20 /* We welcome the use of the Mezzanine engine to anyone, including companies who wish to
21  Build professional software and charge for their product.
22 
23  However there are some practical restrictions, so if your project involves
24  any of the following you should contact us and we will try to work something
25  out:
26  - DRM or Copy Protection of any kind(except Copyrights)
27  - Software Patents You Do Not Wish to Freely License
28  - Any Kind of Linking to Non-GPL licensed Works
29  - Are Currently In Violation of Another Copyright Holder's GPL License
30  - If You want to change our code and not add a few hundred MB of stuff to
31  your distribution
32 
33  These and other limitations could cause serious legal problems if you ignore
34  them, so it is best to simply contact us or the Free Software Foundation, if
35  you have any questions.
36 
37  Joseph Toppi - toppij@gmail.com
38  John Blackwood - makoenergy02@gmail.com
39 */
40 
41 #ifndef _uitextline_h
42 #define _uitextline_h
43 
44 #include "character.h"
45 
46 namespace Mezzanine
47 {
48  namespace UI
49  {
50  class TextLayer;
51  ///////////////////////////////////////////////////////////////////////////////
52  /// @brief This represents a single line of text to be rendered by a TextLayer.
53  /// @details While many of the utilities of the TextLine class are exposed in public interfaces,
54  /// it is important to note that this class as a whole is not intended to be used directly by game
55  /// programmers. These interfaces are available for those that need that level of control but it
56  /// should be noted that manual manipulation of this class may disrupt the behaviors of not only this
57  /// class but it's parent layer as well. Query methods are, of course, safe from this.
58  ///////////////////////////////////////
59  class MEZZ_LIB TextLine
60  {
61  public:
62  /// @brief Basic container type for @ref Character storage by this class.
63  typedef std::list<Character*> CharacterContainer;
64  /// @brief Iterator type for @ref Character instances stored by this class.
65  typedef CharacterContainer::iterator CharacterIterator;
66  /// @brief Const Iterator type for @ref Character instances stored by this class.
67  typedef CharacterContainer::const_iterator ConstCharacterIterator;
68  /// @brief Reverse Iterator type for @ref Character instances stored by this class.
69  typedef CharacterContainer::reverse_iterator ReverseCharacterIterator;
70  /// @brief Const Reverse Iterator type for @ref Character instances stored by this class.
71  typedef CharacterContainer::const_reverse_iterator ReverseConstCharacterIterator;
72  /// @brief An std::pair storing two CharacterIterators, usually for expressing a range.
73  typedef std::pair<CharacterIterator,CharacterIterator> CharacterIteratorPair;
74  /// @brief An std::pair storing a Character and it's offset position (relative to the parent layer).
75  typedef std::pair<Character*,Vector2> OffsetResultPair;
76  protected:
77  /// @internal
78  /// @brief Vector containing all the characters belonging to this TextLine.
79  CharacterContainer Characters;
80  /// @internal
81  /// @brief The parent layer this text line belongs to.
82  TextLayer* Parent;
83  /// @internal
84  /// @brief The current length of this TextLine.
85  Real CurrLength;
86  /// @internal
87  /// @brief The size of the largest glyph on the Y axis.
88  Real TallestHeight;
89  /// @internal
90  /// @brief The offset in pixels from the parent layer on the Y axis.
91  Real PositionOffset;
92  /// @internal
93  /// @brief The alignment of the text on the X axis in this line.
94  UI::LinearAlignment Alignment;
95 
96  /// @internal
97  /// @brief Gets the maximum width this text line can be.
98  Real GetMaxWidth() const;
99  /// @internal
100  /// @brief Gets the character before the last character.
101  virtual Character* GetSecondFromLastCharacter() const = 0;
102  /// @internal
103  /// @brief Recalculates the offset for every character in this line.
104  virtual void RecalculateOffsets() = 0;
105  /// @internal
106  /// @brief Adds a character such that it becomes the last in the sequence.
107  virtual void AppendToBack(Character* ToAppend) = 0;
108  /// @internal
109  /// @brief Adds a series of characters to the end of this line.
110  virtual void AppendToBack(CharacterIterator First, CharacterIterator Last) = 0;
111  public:
112  /// @brief Class constructor.
113  /// @param ParentLayer The TextLayer that this TextLine belongs to.
114  TextLine(TextLayer* ParentLayer);
115  /// @brief Class destructor.
116  virtual ~TextLine();
117 
118  ///////////////////////////////////////////////////////////////////////////////
119  // Utility
120 
121  /// @brief Aligns the text of the caption.
122  /// @details Default value for this is UI::Txt_Middle.
123  /// @param Align The enum value representing the horizontal alignment to be set.
124  void SetAlignment(const UI::LinearAlignment Align);
125  /// @brief Gets the current alignment for the text in this line of text.
126  /// @return Returns a TextAlignment value representing the alignment the text in this line will have.
127  UI::LinearAlignment GetAlignment() const;
128 
129  /// @brief Gets the character at the provided offset as well as the nearest valid position the cursor can take.
130  /// @param Offset The offset from the left side of this TextLine to use when finding the result.
131  /// @return Returns a OffsetResultPair with the "first" member containing a pointer to the character at the offset,
132  /// or NULL if there isn't one and the "second" member containing the closest valid position the cursor can be placed at
133  /// in the form of an offset from this TextLines left edge.
134  OffsetResultPair GetCharacterAndCursorPositionAtOffset(const Real& Offset) const;
135  /// @brief Gets the index of the character at the provided offset.
136  /// @note The index returned is only among the characters in this line and is not indicative of the overall index among all characters in the parent layer.
137  /// @param Offset The offset from the left side of this TextLine to use when finding the result.
138  /// @return Returns an Integer representing the index of the character at the given offset.
139  Integer GetIndexAtOffset(const Real& Offset) const;
140  /// @brief Gets the Offset position of the character at the specified index.
141  /// @note The index provided is only among the characters in this line and is not indicative of the overall index among all characters in the parent layer.
142  /// @param Index The index of the character in this line to get the offset of.
143  /// @return Returns a Real representing the distance in pixels the character at the provided index is from the left side of the TextLine.
144  Real GetOffsetAtIndex(const Integer& Index) const;
145 
146  /// @brief Gets the offset position of the left-most part of this TextLine.
147  /// @return Returns the left-most offset from the left side of this TextLine where the cursor can be placed.
148  Real GetLeftMostCursorPosition() const;
149  /// @brief Gets the offset position of the right-most part of this TextLine.
150  /// @return Returns the right-most offset from the right side of this TextLine where the cursor can be placed.
151  Real GetRightMostCursorPosition() const;
152  /// @brief Gets the offset position of the cursor based on the text order of the layer this text line belongs to.
153  /// @return Returns the left most cursor position if text is ordered left to right, and vice versa.
154  virtual Real GetCursorStartPosition() const = 0;
155  /// @brief Gets the closest valid cursor position to the offset provided.
156  /// @param Offset The offset from the left side of the TextLine.
157  /// @return Returns a Real containing the closest valid offset to the one provided.
158  Real GetClosestCursorPosition(const Real& Offset);
159 
160  ///////////////////////////////////////////////////////////////////////////////
161  // Transform Related Methods
162 
163  /// @brief Sets the offset on the Y axis from the parent layer.
164  /// @warning Adjusting this value manually can create visual artifacts. Only call this manually if you know what you are doing.
165  /// @param Offset The offset in pixels from the top of the parent layer to be this TextLines position.
166  void SetPositionOffset(const Real& Offset);
167  /// @brief Gets the offset on the Y axis from the parent layer.
168  /// @return Returns a Real representing the offset in pixels from the parent layer.
169  Real GetPositionOffset() const;
170  /// @brief Calculates the current length of this text line.
171  /// @note This method will return the length of the non-clipped characters.
172  /// @return Returns a Real representing the current length of this text line.
173  Real GetCurrentLength() const;
174  /// @brief Gets the size of this TextLine on the Y axis.
175  /// @return Returns a Real representing the height of this TextLine.
176  Real GetLineHeight() const;
177 
178  ///////////////////////////////////////////////////////////////////////////////
179  // Character Management
180 
181  /// @brief Adds a Character to the end of this TextLine.
182  /// @param ToAdd The Character to be added.
183  /// @return Returns true if the character was successfully added, false otherwise.
184  Boolean AppendCharacter(Character* ToAdd);
185  /// @brief Adds a series of Characters to the end of this TextLine.
186  /// @param ToAdd A container storing all Characters to attempt to add.
187  /// @return Returns true if all characters were successfully added, false otherwise.
188  Boolean AppendCharacters(CharacterContainer& ToAdd);
189  /// @brief Adds a series of Characters to the end of this TextLine.
190  /// @param Pair An std::pair containing iterators to both the first and last Characters in a sequence to attempt to append.
191  /// @return Returns true if all characters were successfully added, false otherwise.
192  Boolean AppendCharacters(CharacterIteratorPair Pair);
193  /// @brief Adds a series of Characters to the end of this TextLine.
194  /// @param First Iterator to the first Character in the series to be added.
195  /// @param Last Iterator to one passed the last Character in the series to be added.
196  /// @return Returns true if all characters were successfully added, false otherwise.
197  virtual Boolean AppendCharacters(CharacterIterator First, CharacterIterator Last) = 0;
198  /// @brief Adds as many Characters in a range as will fit to this TextLine.
199  /// @param ToAdd A container storing all Characters to attempt to add.
200  /// @return Returns a CharacterIterator to the first character that was not added in the range. This can be the left-most non-added Character when added to
201  /// Left-To-Right TextLines, or the right-most non-added Character in Right-To-Left TextLines.
202  CharacterIterator AppendFittingCharacters(CharacterContainer& ToAdd);
203  /// @brief Adds as many Characters in a range as will fit to this TextLine.
204  /// @param Pair An std::pair containing iterators to both the first and last Characters in a sequence to attempt to append.
205  /// @return Returns a CharacterIterator to the first character that was not added in the range. This can be the left-most non-added Character when added to
206  /// Left-To-Right TextLines, or the right-most non-added Character in Right-To-Left TextLines.
207  CharacterIterator AppendFittingCharacters(CharacterIteratorPair Pair);
208  /// @brief Adds as many Characters in a range as will fit to this TextLine.
209  /// @param First Iterator to the first Character in the series to be added.
210  /// @param Last Iterator to one passed the last Character in the series to be added.
211  /// @return Returns a CharacterIterator to the first character that was not added in the range. This can be the left-most non-added Character when added to
212  /// Left-To-Right TextLines, or the right-most non-added Character in Right-To-Left TextLines.
213  virtual CharacterIterator AppendFittingCharacters(CharacterIterator First, CharacterIterator Last) = 0;
214 
215  /// @brief Gets the character in this textline at the specified index.
216  /// @param Index The index of the character to retrieve.
217  /// @return Returns a pointer to the character at the requested index, or NULL if out of bounds.
218  Character* GetCharacterAtIndex(const UInt32& Index);
219  /// @brief Gets the character in this textline at the specified offset.
220  /// @param Offset The offset from the parent position to use when checking characters.
221  /// @return Returns a pointer to the character at the requested offset, or NULL of none exists.
222  Character* GetCharacterAtOffset(const Real& Offset);
223  /// @brief Gets the number of characters in this TextLine.
224  /// @return Returns a UInt32 containing the number of characters in this TextLine.
225  UInt32 GetNumCharacters() const;
226  /// @brief Removes all characters from this TextLine.
227  void RemoveAllCharacters();
228 
229  /// @brief Gets the first character in this TextLine.
230  /// @note The first character is based on the order in which the characters are read. If the characters are
231  /// meant to be read left-to-right then this will be the left most character. If the characters are meant to
232  /// be read right-to-left, this will be the right most character.
233  /// @return Returns an iterator to the first character in this TextLine.
234  virtual CharacterIterator GetFirstCharacter() = 0;
235  /// @brief Gets the last character in this TextLine.
236  /// @note The last character is based on the order in which the characters are read. If the characters are
237  /// meant to be read left-to-right then this will be the right most character. If the characters are meant to
238  /// be read right-to-left, this will be the left most character.
239  /// @return Returns an iterator to the last character in this TextLine.
240  virtual CharacterIterator GetLastCharacter() = 0;
241  /// @brief Gets an iterator to the next Character.
242  /// @param Current An iterator to a valid Character.
243  /// @return Returns an iterator to the next Character in the sequence.
244  virtual CharacterIterator GetNextCharacter(CharacterIterator Current) = 0;
245  /// @brief Removes the character at the start of this TextLine.
246  virtual void RemoveFirstCharacter() = 0;
247  /// @brief Removes the character at the end of this TextLine.
248  virtual void RemoveLastCharacter() = 0;
249 
250  /// @brief Gets an iterator to the first Character.
251  /// @return Returns an iterator to the first Character being stored by this TextLine.
252  CharacterIterator BeginCharacter();
253  /// @brief Gets an iterator to one passed the last Character.
254  /// @return Returns an iterator to one passed the last Character being stored by this TextLine.
255  CharacterIterator EndCharacter();
256  /// @brief Gets a const iterator to the first Character.
257  /// @return Returns a const iterator to the first Character being stored by this TextLine.
258  ConstCharacterIterator BeginCharacter() const;
259  /// @brief Gets an iterator to one passed the last Character.
260  /// @return Returns an iterator to one passed the last Character being stored by this TextLine.
261  ConstCharacterIterator EndCharacter() const;
262  };//TextLine
263 
264  ///////////////////////////////////////////////////////////////////////////////
265  /// @brief This is a TextLine specialization class for text read from the left to the right.
266  /// @details
267  ///////////////////////////////////////
268  class MEZZ_LIB LeftToRightTextLine : public TextLine
269  {
270  protected:
271  /// @copydoc TextLine::GetSecondFromLastCharacter()
272  Character* GetSecondFromLastCharacter() const;
273  /// @copydoc TextLine::RecalculateOffsets()
274  void RecalculateOffsets();
275  /// @copydoc TextLine::AppendToBack(Character* ToAppend)
276  void AppendToBack(Character* ToAppend);
277  /// @copydoc TextLine::AppendToBack(CharacterIterator First, CharacterIterator Last)
278  void AppendToBack(CharacterIterator First, CharacterIterator Last);
279  public:
280  /// @brief Class constructor.
281  /// @param ParentLayer The TextLayer that this TextLine belongs to.
282  LeftToRightTextLine(TextLayer* ParentLayer);
283  /// @brief Class destructor.
284  virtual ~LeftToRightTextLine();
285 
286  ///////////////////////////////////////////////////////////////////////////////
287  // Utility
288 
289  /// @copydoc TextLine::GetCursorStartPosition() const
290  Real GetCursorStartPosition() const;
291 
292  ///////////////////////////////////////////////////////////////////////////////
293  // Character Management
294 
295  /// @copydoc TextLine::AppendCharacters(CharacterIterator First, CharacterIterator Last)
296  Boolean AppendCharacters(CharacterIterator First, CharacterIterator Last);
297  /// @copydoc TextLine::AppendCharactersAppendFittingCharacters(CharacterIterator First, CharacterIterator Last)
298  CharacterIterator AppendFittingCharacters(CharacterIterator First, CharacterIterator Last);
299 
300  /// @copydoc TextLine::GetFirstCharacter()
301  CharacterIterator GetFirstCharacter();
302  /// @copydoc TextLine::GetLastCharacter()
303  CharacterIterator GetLastCharacter();
304  /// @copydoc TextLine::GetNextCharacter(CharacterIterator Current)
305  CharacterIterator GetNextCharacter(CharacterIterator Current);
306  /// @copydoc TextLine::RemoveFirstCharacter()
307  void RemoveFirstCharacter();
308  /// @copydoc TextLine::RemoveLastCharacter()
309  void RemoveLastCharacter();
310  };//LeftToRightTextLine
311 
312  ///////////////////////////////////////////////////////////////////////////////
313  /// @brief This is a TextLine specialization class for text read from the right to the left.
314  /// @details
315  ///////////////////////////////////////
316  class MEZZ_LIB RightToLeftTextLine : public TextLine
317  {
318  protected:
319  /// @copydoc TextLine::GetSecondFromLastCharacter()
320  Character* GetSecondFromLastCharacter() const;
321  /// @copydoc TextLine::RecalculateOffsets()
322  void RecalculateOffsets();
323  /// @copydoc TextLine::AppendToBack(Character* ToAppend)
324  void AppendToBack(Character* ToAppend);
325  /// @copydoc TextLine::AppendToBack(CharacterIterator First, CharacterIterator Last)
326  void AppendToBack(CharacterIterator First, CharacterIterator Last);
327  public:
328  /// @brief Class constructor.
329  /// @param ParentLayer The TextLayer that this TextLine belongs to.
330  RightToLeftTextLine(TextLayer* ParentLayer);
331  /// @brief Class destructor.
332  virtual ~RightToLeftTextLine();
333 
334  ///////////////////////////////////////////////////////////////////////////////
335  // Utility
336 
337  /// @copydoc TextLine::GetCursorStartPosition() const
338  Real GetCursorStartPosition() const;
339 
340  ///////////////////////////////////////////////////////////////////////////////
341  // Character Management
342 
343  /// @copydoc TextLine::AppendCharacters(CharacterIterator First, CharacterIterator Last)
344  Boolean AppendCharacters(CharacterIterator First, CharacterIterator Last);
345  /// @copydoc TextLine::AppendCharactersAppendFittingCharacters(CharacterIterator First, CharacterIterator Last)
346  CharacterIterator AppendFittingCharacters(CharacterIterator First, CharacterIterator Last);
347 
348  /// @copydoc TextLine::GetFirstCharacter()
349  CharacterIterator GetFirstCharacter();
350  /// @copydoc TextLine::GetLastCharacter()
351  CharacterIterator GetLastCharacter();
352  /// @copydoc TextLine::GetNextCharacter(CharacterIterator Current)
353  CharacterIterator GetNextCharacter(CharacterIterator Current);
354  /// @copydoc TextLine::RemoveFirstCharacter()
355  void RemoveFirstCharacter();
356  /// @copydoc TextLine::RemoveLastCharacter()
357  void RemoveLastCharacter();
358  };//RightToLeftTextLine
359  }//UI
360 }//Mezzanine
361 
362 #endif
Generated on Mon Jan 6 2014 20:58:06 for MezzanineEngine by doxygen 1.8.4