summaryrefslogtreecommitdiffstats
path: root/ui/gfx/font_list.h
blob: 2b67c4a13e2cf2e5b7bc6e93c93eac128ef5a3fa (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
// Copyright (c) 2012 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef UI_GFX_FONT_LIST_H_
#define UI_GFX_FONT_LIST_H_

#include <string>
#include <vector>

#include "base/memory/ref_counted.h"
#include "ui/gfx/font.h"
#include "ui/gfx/gfx_export.h"

namespace gfx {

class FontListImpl;

// FontList represents a list of fonts and provides metrics which are common
// across the fonts.  FontList is copyable and quite cheap to copy.
//
// The format of font description strings is a subset of that used by Pango, as
// described at
// http://developer.gnome.org/pango/stable/pango-Fonts.html#pango-font-description-from-string
//
// Pango font description strings should not be passed directly into FontLists.
//
// The format is "<FONT_FAMILY_LIST>,[STYLES] <SIZE>", where:
// - FONT_FAMILY_LIST is a comma-separated list of font family names,
// - STYLES is an optional space-separated list of style names (case-sensitive
//   "Bold" and "Italic" are supported), and
// - SIZE is an integer font size in pixels with the suffix "px".
//
// Here are examples of valid font description strings:
// - "Arial, Helvetica, Bold Italic 14px"
// - "Arial, 14px"
class GFX_EXPORT FontList {
 public:
  // Parses a FontList description string into |families_out|, |style_out| (a
  // bitfield of gfx::Font::Style values), and |size_pixels_out|. Returns true
  // if the string is properly-formed.
  static bool ParseDescription(const std::string& description,
                               std::vector<std::string>* families_out,
                               int* style_out,
                               int* size_pixels_out);

  // Creates a font list with default font names, size and style, which are
  // specified by SetDefaultFontDescription().
  FontList();

  // Creates a font list that is a clone of another font list.
  FontList(const FontList& other);

  // Creates a font list from a string representing font names, styles, and
  // size.
  explicit FontList(const std::string& font_description_string);

  // Creates a font list from font names, styles and size.
  FontList(const std::vector<std::string>& font_names,
           int font_style,
           int font_size);

  // Creates a font list from a Font vector.
  // All fonts in this vector should have the same style and size.
  explicit FontList(const std::vector<Font>& fonts);

  // Creates a font list from a Font.
  explicit FontList(const Font& font);

  ~FontList();

  // Copies the given font list into this object.
  FontList& operator=(const FontList& other);

  // Sets the description string for default FontList construction. If it's
  // empty, FontList will initialize using the default Font constructor.
  //
  // The client code must call this function before any call of the default
  // constructor. This should be done on the UI thread.
  //
  // ui::ResourceBundle may call this function more than once when UI language
  // is changed.
  static void SetDefaultFontDescription(const std::string& font_description);

  // Returns a new FontList with the same font names but resized and the given
  // style. |size_delta| is the size in pixels to add to the current font size.
  // |font_style| specifies the new style, which is a bitmask of the values:
  // Font::BOLD, Font::ITALIC and Font::UNDERLINE.
  FontList Derive(int size_delta, int font_style) const;

  // Returns a new FontList with the same font names and style but resized.
  // |size_delta| is the size in pixels to add to the current font size.
  FontList DeriveWithSizeDelta(int size_delta) const;

  // Returns a new FontList with the same font names and size but the given
  // style. |font_style| specifies the new style, which is a bitmask of the
  // values: Font::BOLD, Font::ITALIC and Font::UNDERLINE.
  FontList DeriveWithStyle(int font_style) const;

  // Shrinks the font size until the font list fits within |height| while
  // having its cap height vertically centered. Returns a new FontList with
  // the correct height.
  //
  // The expected layout:
  //   +--------+-----------------------------------------------+------------+
  //   |        | y offset                                      | space      |
  //   |        +--------+-------------------+------------------+ above      |
  //   |        |        |                   | internal leading | cap height |
  //   | box    | font   | ascent (baseline) +------------------+------------+
  //   | height | height |                   | cap height                    |
  //   |        |        |-------------------+------------------+------------+
  //   |        |        | descent (height - baseline)          | space      |
  //   |        +--------+--------------------------------------+ below      |
  //   |        | space at bottom                               | cap height |
  //   +--------+-----------------------------------------------+------------+
  // Goal:
  //     center of box height == center of cap height
  //     (i.e. space above cap height == space below cap height)
  // Restrictions:
  //     y offset >= 0
  //     space at bottom >= 0
  //     (i.e. Entire font must be visible inside the box.)
  gfx::FontList DeriveWithHeightUpperBound(int height) const;

  // Returns the height of this font list, which is max(ascent) + max(descent)
  // for all the fonts in the font list.
  int GetHeight() const;

  // Returns the baseline of this font list, which is max(baseline) for all the
  // fonts in the font list.
  int GetBaseline() const;

  // Returns the cap height of this font list.
  // Currently returns the cap height of the primary font.
  int GetCapHeight() const;

  // Returns the expected number of horizontal pixels needed to display the
  // specified length of characters. Call GetStringWidth() to retrieve the
  // actual number.
  int GetExpectedTextWidth(int length) const;

  // Returns the |gfx::Font::FontStyle| style flags for this font list.
  int GetFontStyle() const;

  // Returns the font size in pixels.
  int GetFontSize() const;

  // Returns the Font vector.
  const std::vector<Font>& GetFonts() const;

  // Returns the first font in the list.
  const Font& GetPrimaryFont() const;

 private:
  explicit FontList(FontListImpl* impl);

  static const scoped_refptr<FontListImpl>& GetDefaultImpl();

  scoped_refptr<FontListImpl> impl_;
};

}  // namespace gfx

#endif  // UI_GFX_FONT_LIST_H_