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/ColorUtils.h"
  20 #include "utils/Geometry.h"
  21
  22 class CLabelInfo
  23 {
  24 public:
  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  */
  69 class CGUILabel
  70 {
  71 public:
  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   CGUILabel(const CGUILabel& label);
  89
  90   virtual ~CGUILabel() = default;
  91
  92   /*! \brief Process the label
  93    \return bool stating if process caused control to change
  94    */
  95   bool Process(unsigned int currentTime);
  96
  97   /*! \brief Render the label on screen
  98    */
  99   void Render();
 100
 101   /*! \brief Set the maximal extent of the label
 102    Sets the maximal size and positioning that the label may render in.  Note that `textwidth>` can override
 103    this, and `<textoffsetx>` and `<textoffsety>` may also allow the label to be moved outside this rectangle.
 104    */
 105   bool SetMaxRect(float x, float y, float w, float h);
 106
 107   bool SetAlign(uint32_t align);
 108
 109   /*! \brief Set the text to be displayed in the label
 110    Updates the label control and recomputes final position and size
 111    \param text std::string to set as this labels text
 112    \sa SetTextW, SetStyledText
 113    */
 114   bool SetText(const std::string &label);
 115
 116   /*! \brief Set the text to be displayed in the label
 117    Updates the label control and recomputes final position and size
 118    \param text std::wstring to set as this labels text
 119    \sa SetText, SetStyledText
 120    */
 121   bool SetTextW(const std::wstring &label);
 122
 123   /*! \brief Set styled text to be displayed in the label
 124    Updates the label control and recomputes final position and size
 125    \param text styled text to set.
 126    \param colors colors referenced in the styled text.
 127    \sa SetText, SetTextW
 128    */
 129   bool SetStyledText(const vecText& text, const std::vector<UTILS::COLOR::Color>& colors);
 130
 131   /*! \brief Set the color to use for the label
 132    Sets the color to be used for this label.  Takes effect at the next render
 133    \param color color to be used for the label
 134    */
 135   bool SetColor(COLOR color);
 136
 137   /*! \brief Set the final layout of the current text
 138    Overrides the calculated layout of the current text, forcing a particular size and position
 139    \param rect CRect containing the extents of the current text
 140    \sa GetRenderRect, UpdateRenderRect
 141    */
 142   void SetRenderRect(const CRect& rect) { m_renderRect = rect; }
 143
 144   /*! \brief Set whether or not this label control should scroll
 145    \param scrolling true if this label should scroll.
 146    */
 147   bool SetScrolling(bool scrolling);
 148
 149   /*! \brief Set max. text scroll count
 150   */
 151   void SetScrollLoopCount(unsigned int loopCount) { m_maxScrollLoops = loopCount; }
 152
 153   /*! \brief Set how this label should handle overflowing text.
 154    \param overflow the overflow type
 155    \sa OVER_FLOW
 156    */
 157   bool SetOverflow(OVER_FLOW overflow);
 158
 159   /*!
 160    * \brief Set if the text truncate (and ellipsis "...") must be done in reverse (on LTR text by default on the left).
 161    * \param isReversed Set true to reversed behaviour
 162    */
 163   void SetReversedTruncate(bool isReversed) { m_isReversedTruncate = isReversed; }
 164
 165   /*! \brief Set this label invalid.  Forces an update of the control
 166    */
 167   void SetInvalid();
 168
 169   /*! \brief Update this labels colors
 170    */
 171   bool UpdateColors();
 172
 173   /*! \brief Returns the precalculated final layout of the current text
 174    \return CRect containing the extents of the current text
 175    \sa SetRenderRect, UpdateRenderRect
 176    */
 177   const CRect& GetRenderRect() const { return m_renderRect; }
 178
 179   /*! \brief Returns the precalculated full width of the current text, regardless of layout
 180    \return full width of the current text
 181    \sa CalcTextWidth
 182    */
 183   float GetTextWidth() const { return m_textLayout.GetTextWidth(); }
 184
 185   /*! \brief Returns the maximal width that this label can render into
 186    \return Maximal width that this label can render into. Note that this may differ from the
 187            amount given in SetMaxRect as offsets and text width overrides have been taken into account.
 188    \sa SetMaxRect
 189    */
 190   float GetMaxWidth() const;
 191
 192   /*! \brief Calculates the width of some text
 193    \param text std::wstring of text whose width we want
 194    \return width of the given text
 195    \sa GetTextWidth
 196    */
 197   float CalcTextWidth(const std::wstring& text) const { return m_textLayout.GetTextWidth(text); }
 198
 199   const CLabelInfo& GetLabelInfo() const { return m_label; }
 200   CLabelInfo& GetLabelInfo() { return m_label; }
 201
 202   /*! \brief Check a left aligned and right aligned label for overlap and cut the labels off so that no overlap occurs
 203
 204    If a left-aligned label occupies some of the same space on screen as a right-aligned label, then we may be able to
 205    correct for this by restricting the width of one or both of them. This routine checks two labels to see whether they
 206    satisfy this assumption and, if so, adjusts the render rect of both labels so that they no longer do so.  The order
 207    of the two labels is not important, but we do assume that the left-aligned label is also the left-most on screen, and
 208    that the right-aligned label is the right most on-screen, so that they overlap due to the fact that one or both of
 209    the labels are longer than anticipated.  In the following diagram, [R...[R  R] refers to the maximal allowed and
 210    actual space occupied by the right label.  Similarly, [L   L]...L] refers to the maximal and actual space occupied
 211    by the left label.  | refers to the central cutting point, i.e. the point that would divide the maximal allowed
 212    overlap perfectly in two.  There are 3 scenarios to consider:
 213
 214    cut
 215    [L       [R...[R  L].|..........L]         R]     left label ends to the left of the cut -> just crop the left label.
 216    [L       [R.....[R   |      L]..L]         R]     both left and right labels occupy more than the cut allows, so crop both.
 217    [L       [R..........|.[R   L]..L]         R]     right label ends to the right of the cut -> just crop the right label.
 218
 219    \param label1 First label to check
 220    \param label2 Second label to check
 221    */
 222   static bool CheckAndCorrectOverlap(CGUILabel &label1, CGUILabel &label2);
 223
 224 protected:
 225   UTILS::COLOR::Color GetColor() const;
 226
 227   /*! \brief Computes the final layout of the text
 228    Uses the maximal position and width of the text, as well as the text length
 229    and alignment to compute the final render rect of the text.
 230    \sa GetRenderRect, SetRenderRect
 231    */
 232   void UpdateRenderRect();
 233
 234 private:
 235   CLabelInfo     m_label;
 236   CGUITextLayout m_textLayout;
 237
 238   bool           m_scrolling;
 239   OVER_FLOW      m_overflowType;
 240   bool m_isReversedTruncate{false};
 241   CScrollInfo    m_scrollInfo;
 242   CRect          m_renderRect;   ///< actual sizing of text
 243   CRect          m_maxRect;      ///< maximum sizing of text
 244   bool m_invalid = true; ///< if true, the label needs recomputing
 245   COLOR m_color = COLOR_TEXT; ///< color to render text \sa SetColor, GetColor
 246   unsigned int   m_maxScrollLoops = ~0U;
 247 };