/xbmc/guilib/GUILabel.h

  1/*
  2 *  Copyright (C) 2005-2018 Team Kodi
  3 *  This file is part of Kodi - https://kodi.tv
  4 *
  5 *  SPDX-License-Identifier: GPL-2.0-or-later
  6 *  See LICENSES/README.md for more information.
  7 */
  8
  9#pragma once
 10
 11/*!
 12\file GUILabel.h
 13\brief
 14*/
 15
 16#include "GUIFont.h"
 17#include "GUITextLayout.h"
 18#include "guiinfo/GUIInfoColor.h"
 19#include "utils/Color.h"
 20#include "utils/Geometry.h"
 21
 22class CLabelInfo
 23{
 24public:
 25  CLabelInfo():
 26    scrollSuffix(" | ")
 27  {
 28    font = NULL;
 29    align = XBFONT_LEFT;
 30    offsetX = offsetY = 0;
 31    width = 0;
 32    angle = 0;
 33    scrollSpeed = CScrollInfo::defaultSpeed;
 34  };
 35  bool UpdateColors()
 36  {
 37    bool changed = false;
 38
 39    changed |= textColor.Update();
 40    changed |= shadowColor.Update();
 41    changed |= selectedColor.Update();
 42    changed |= disabledColor.Update();
 43    changed |= focusedColor.Update();
 44    changed |= invalidColor.Update();
 45
 46    return changed;
 47  };
 48
 49  KODI::GUILIB::GUIINFO::CGUIInfoColor textColor;
 50  KODI::GUILIB::GUIINFO::CGUIInfoColor shadowColor;
 51  KODI::GUILIB::GUIINFO::CGUIInfoColor selectedColor;
 52  KODI::GUILIB::GUIINFO::CGUIInfoColor disabledColor;
 53  KODI::GUILIB::GUIINFO::CGUIInfoColor focusedColor;
 54  KODI::GUILIB::GUIINFO::CGUIInfoColor invalidColor;
 55  uint32_t align;
 56  float offsetX;
 57  float offsetY;
 58  float width;
 59  float angle;
 60  CGUIFont *font;
 61  int scrollSpeed;
 62  std::string scrollSuffix;
 63};
 64
 65/*!
 66 \ingroup controls, labels
 67 \brief Class for rendering text labels.  Handles alignment and rendering of text within a control.
 68 */
 69class CGUILabel
 70{
 71public:
 72  /*! \brief allowed color categories for labels, as defined by the skin
 73   */
 74  enum COLOR { COLOR_TEXT = 0,
 75               COLOR_SELECTED,
 76               COLOR_FOCUSED,
 77               COLOR_DISABLED,
 78               COLOR_INVALID };
 79
 80  /*! \brief allowed overflow handling techniques for labels, as defined by the skin
 81   */
 82  enum OVER_FLOW { OVER_FLOW_TRUNCATE = 0,
 83                   OVER_FLOW_SCROLL,
 84                   OVER_FLOW_WRAP,
 85                   OVER_FLOW_CLIP };
 86
 87  CGUILabel(float posX, float posY, float width, float height, const CLabelInfo& labelInfo, OVER_FLOW overflow = OVER_FLOW_TRUNCATE);
 88  virtual ~CGUILabel(void);
 89
 90  /*! \brief Process the label
 91   \return bool stating if process caused control to change
 92   */
 93  bool Process(unsigned int currentTime);
 94
 95  /*! \brief Render the label on screen
 96   */
 97  void Render();
 98
 99  /*! \brief Set the maximal extent of the label
100   Sets the maximal size and positioning that the label may render in.  Note that `textwidth>` can override
101   this, and `<textoffsetx>` and `<textoffsety>` may also allow the label to be moved outside this rectangle.
102   */
103  bool SetMaxRect(float x, float y, float w, float h);
104
105  bool SetAlign(uint32_t align);
106
107  /*! \brief Set the text to be displayed in the label
108   Updates the label control and recomputes final position and size
109   \param text std::string to set as this labels text
110   \sa SetTextW, SetStyledText
111   */
112  bool SetText(const std::string &label);
113
114  /*! \brief Set the text to be displayed in the label
115   Updates the label control and recomputes final position and size
116   \param text std::wstring to set as this labels text
117   \sa SetText, SetStyledText
118   */
119  bool SetTextW(const std::wstring &label);
120
121  /*! \brief Set styled text to be displayed in the label
122   Updates the label control and recomputes final position and size
123   \param text styled text to set.
124   \param colors colors referenced in the styled text.
125   \sa SetText, SetTextW
126   */
127  bool SetStyledText(const vecText &text, const std::vector<UTILS::Color> &colors);
128
129  /*! \brief Set the color to use for the label
130   Sets the color to be used for this label.  Takes effect at the next render
131   \param color color to be used for the label
132   */
133  bool SetColor(COLOR color);
134
135  /*! \brief Set the final layout of the current text
136   Overrides the calculated layout of the current text, forcing a particular size and position
137   \param rect CRect containing the extents of the current text
138   \sa GetRenderRect, UpdateRenderRect
139   */
140  void SetRenderRect(const CRect &rect) { m_renderRect = rect; };
141
142  /*! \brief Set whether or not this label control should scroll
143   \param scrolling true if this label should scroll.
144   */
145  bool SetScrolling(bool scrolling);
146
147  /*! \brief Set max. text scroll count
148  */
149  void SetScrollLoopCount(unsigned int loopCount) { m_maxScrollLoops = loopCount; };
150
151  /*! \brief Set how this label should handle overflowing text.
152   \param overflow the overflow type
153   \sa OVER_FLOW
154   */
155  bool SetOverflow(OVER_FLOW overflow);
156
157  /*! \brief Set this label invalid.  Forces an update of the control
158   */
159  void SetInvalid();
160
161  /*! \brief Update this labels colors
162   */
163  bool UpdateColors();
164
165  /*! \brief Returns the precalculated final layout of the current text
166   \return CRect containing the extents of the current text
167   \sa SetRenderRect, UpdateRenderRect
168   */
169  const CRect &GetRenderRect() const { return m_renderRect; };
170
171  /*! \brief Returns the precalculated full width of the current text, regardless of layout
172   \return full width of the current text
173   \sa CalcTextWidth
174   */
175  float GetTextWidth() const { return m_textLayout.GetTextWidth(); };
176
177  /*! \brief Returns the maximal width that this label can render into
178   \return Maximal width that this label can render into. Note that this may differ from the
179           amount given in SetMaxRect as offsets and text width overrides have been taken into account.
180   \sa SetMaxRect
181   */
182  float GetMaxWidth() const;
183
184  /*! \brief Calculates the width of some text
185   \param text std::wstring of text whose width we want
186   \return width of the given text
187   \sa GetTextWidth
188   */
189  float CalcTextWidth(const std::wstring &text) const { return m_textLayout.GetTextWidth(text); };
190
191  const CLabelInfo& GetLabelInfo() const { return m_label; };
192  CLabelInfo &GetLabelInfo() { return m_label; };
193
194  /*! \brief Check a left aligned and right aligned label for overlap and cut the labels off so that no overlap occurs
195
196   If a left-aligned label occupies some of the same space on screen as a right-aligned label, then we may be able to
197   correct for this by restricting the width of one or both of them. This routine checks two labels to see whether they
198   satisfy this assumption and, if so, adjusts the render rect of both labels so that they no longer do so.  The order
199   of the two labels is not important, but we do assume that the left-aligned label is also the left-most on screen, and
200   that the right-aligned label is the right most on-screen, so that they overlap due to the fact that one or both of
201   the labels are longer than anticipated.  In the following diagram, [R...[R  R] refers to the maximal allowed and
202   actual space occupied by the right label.  Similarly, [L   L]...L] refers to the maximal and actual space occupied
203   by the left label.  | refers to the central cutting point, i.e. the point that would divide the maximal allowed
204   overlap perfectly in two.  There are 3 scenarios to consider:
205
206   cut
207   [L       [R...[R  L].|..........L]         R]     left label ends to the left of the cut -> just crop the left label.
208   [L       [R.....[R   |      L]..L]         R]     both left and right labels occupy more than the cut allows, so crop both.
209   [L       [R..........|.[R   L]..L]         R]     right label ends to the right of the cut -> just crop the right label.
210
211   \param label1 First label to check
212   \param label2 Second label to check
213   */
214  static bool CheckAndCorrectOverlap(CGUILabel &label1, CGUILabel &label2);
215
216protected:
217  UTILS::Color GetColor() const;
218
219  /*! \brief Computes the final layout of the text
220   Uses the maximal position and width of the text, as well as the text length
221   and alignment to compute the final render rect of the text.
222   \sa GetRenderRect, SetRenderRect
223   */
224  void UpdateRenderRect();
225
226private:
227  CLabelInfo     m_label;
228  CGUITextLayout m_textLayout;
229
230  bool           m_scrolling;
231  OVER_FLOW      m_overflowType;
232  CScrollInfo    m_scrollInfo;
233  CRect          m_renderRect;   ///< actual sizing of text
234  CRect          m_maxRect;      ///< maximum sizing of text
235  bool           m_invalid;      ///< if true, the label needs recomputing
236  COLOR          m_color;        ///< color to render text \sa SetColor, GetColor
237  unsigned int   m_maxScrollLoops = ~0U;
238};