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   /*! \brief Set this label invalid.  Forces an update of the control
 160    */
 161   void SetInvalid();
 162
 163   /*! \brief Update this labels colors
 164    */
 165   bool UpdateColors();
 166
 167   /*! \brief Returns the precalculated final layout of the current text
 168    \return CRect containing the extents of the current text
 169    \sa SetRenderRect, UpdateRenderRect
 170    */
 171   const CRect& GetRenderRect() const { return m_renderRect; }
 172
 173   /*! \brief Returns the precalculated full width of the current text, regardless of layout
 174    \return full width of the current text
 175    \sa CalcTextWidth
 176    */
 177   float GetTextWidth() const { return m_textLayout.GetTextWidth(); }
 178
 179   /*! \brief Returns the maximal width that this label can render into
 180    \return Maximal width that this label can render into. Note that this may differ from the
 181            amount given in SetMaxRect as offsets and text width overrides have been taken into account.
 182    \sa SetMaxRect
 183    */
 184   float GetMaxWidth() const;
 185
 186   /*! \brief Calculates the width of some text
 187    \param text std::wstring of text whose width we want
 188    \return width of the given text
 189    \sa GetTextWidth
 190    */
 191   float CalcTextWidth(const std::wstring& text) const { return m_textLayout.GetTextWidth(text); }
 192
 193   const CLabelInfo& GetLabelInfo() const { return m_label; }
 194   CLabelInfo& GetLabelInfo() { return m_label; }
 195
 196   /*! \brief Check a left aligned and right aligned label for overlap and cut the labels off so that no overlap occurs
 197
 198    If a left-aligned label occupies some of the same space on screen as a right-aligned label, then we may be able to
 199    correct for this by restricting the width of one or both of them. This routine checks two labels to see whether they
 200    satisfy this assumption and, if so, adjusts the render rect of both labels so that they no longer do so.  The order
 201    of the two labels is not important, but we do assume that the left-aligned label is also the left-most on screen, and
 202    that the right-aligned label is the right most on-screen, so that they overlap due to the fact that one or both of
 203    the labels are longer than anticipated.  In the following diagram, [R...[R  R] refers to the maximal allowed and
 204    actual space occupied by the right label.  Similarly, [L   L]...L] refers to the maximal and actual space occupied
 205    by the left label.  | refers to the central cutting point, i.e. the point that would divide the maximal allowed
 206    overlap perfectly in two.  There are 3 scenarios to consider:
 207
 208    cut
 209    [L       [R...[R  L].|..........L]         R]     left label ends to the left of the cut -> just crop the left label.
 210    [L       [R.....[R   |      L]..L]         R]     both left and right labels occupy more than the cut allows, so crop both.
 211    [L       [R..........|.[R   L]..L]         R]     right label ends to the right of the cut -> just crop the right label.
 212
 213    \param label1 First label to check
 214    \param label2 Second label to check
 215    */
 216   static bool CheckAndCorrectOverlap(CGUILabel &label1, CGUILabel &label2);
 217
 218 protected:
 219   UTILS::COLOR::Color GetColor() const;
 220
 221   /*! \brief Computes the final layout of the text
 222    Uses the maximal position and width of the text, as well as the text length
 223    and alignment to compute the final render rect of the text.
 224    \sa GetRenderRect, SetRenderRect
 225    */
 226   void UpdateRenderRect();
 227
 228 private:
 229   CLabelInfo     m_label;
 230   CGUITextLayout m_textLayout;
 231
 232   bool           m_scrolling;
 233   OVER_FLOW      m_overflowType;
 234   CScrollInfo    m_scrollInfo;
 235   CRect          m_renderRect;   ///< actual sizing of text
 236   CRect          m_maxRect;      ///< maximum sizing of text
 237   bool           m_invalid;      ///< if true, the label needs recomputing
 238   COLOR          m_color;        ///< color to render text \sa SetColor, GetColor
 239   unsigned int   m_maxScrollLoops = ~0U;
 240 };