1// Copyright (c) 2012 The Chromium Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5#ifndef UI_GFX_FONT_LIST_H_
6#define UI_GFX_FONT_LIST_H_
7
8#include <string>
9#include <vector>
10
11#include "ui/base/ui_export.h"
12#include "ui/gfx/font.h"
13
14namespace gfx {
15
16// FontList represents a list of fonts either in the form of Font vector or in
17// the form of a string representing font names, styles, and size.
18//
19// The string representation is in the form "FAMILY_LIST [STYLE_OPTIONS] SIZE",
20// where FAMILY_LIST is a comma separated list of families terminated by a
21// comma, STYLE_OPTIONS is a whitespace separated list of words where each word
22// describes one of style, variant, weight, stretch, or gravity, and SIZE is
23// a decimal number followed by "px" for absolute size. STYLE_OPTIONS may be
24// absent.
25//
26// The string format complies with that of Pango detailed at
27// http://developer.gnome.org/pango/stable/pango-Fonts.html#pango-font-description-from-string
28//
29// FontList could be initialized either way without conversion to the other
30// form. The conversion to the other form is done only when asked to get the
31// other form.
32//
33// FontList allows operator= since FontList is a data member type in RenderText,
34// and operator= is used in RenderText::SetFontList().
35class UI_EXPORT FontList {
36 public:
37  // Creates a font list with a Font with default name and style.
38  FontList();
39
40  // Creates a font list from a string representing font names, styles, and
41  // size.
42  explicit FontList(const std::string& font_description_string);
43
44  // Creates a font list from font names, styles and size.
45  FontList(const std::vector<std::string>& font_names,
46           int font_style,
47           int font_size);
48
49  // Creates a font list from a Font vector.
50  // All fonts in this vector should have the same style and size.
51  explicit FontList(const std::vector<Font>& fonts);
52
53  // Creates a font list from a Font.
54  explicit FontList(const Font& font);
55
56  ~FontList();
57
58  // Returns a new FontList with the given |font_style| flags.
59  FontList DeriveFontList(int font_style) const;
60
61  // Returns a new FontList with the same font names and style but with the
62  // given font |size| in pixels.
63  FontList DeriveFontListWithSize(int size) const;
64
65  // Returns a new FontList with the same font names and style but resized.
66  // |size_delta| is the size in pixels to add to the current font size.
67  FontList DeriveFontListWithSizeDelta(int size_delta) const;
68
69  // Returns a new FontList with the same font names but resized and the given
70  // style. |size_delta| is the size in pixels to add to the current font size.
71  // |font_style| specifies the new style, which is a bitmask of the values:
72  // Font::BOLD, Font::ITALIC and Font::UNDERLINE.
73  FontList DeriveFontListWithSizeDeltaAndStyle(int size_delta,
74                                               int font_style) const;
75
76  // Returns the height of this font list, which is max(ascent) + max(descent)
77  // for all the fonts in the font list.
78  int GetHeight() const;
79
80  // Returns the baseline of this font list, which is max(baseline) for all the
81  // fonts in the font list.
82  int GetBaseline() const;
83
84  // Returns the number of horizontal pixels needed to display |text|.
85  int GetStringWidth(const base::string16& text) const;
86
87  // Returns the expected number of horizontal pixels needed to display the
88  // specified length of characters. Call GetStringWidth() to retrieve the
89  // actual number.
90  int GetExpectedTextWidth(int length) const;
91
92  // Returns the |gfx::Font::FontStyle| style flags for this font list.
93  int GetFontStyle() const;
94
95  // Returns a string representing font names, styles, and size. If the FontList
96  // is initialized by a vector of Font, use the first font's style and size
97  // for the description.
98  const std::string& GetFontDescriptionString() const;
99
100  // Returns the font size in pixels.
101  int GetFontSize() const;
102
103  // Returns the Font vector.
104  const std::vector<Font>& GetFonts() const;
105
106  // Returns the first font in the list.
107  const Font& GetPrimaryFont() const;
108
109 private:
110  // Extracts common font height and baseline into |common_height_| and
111  // |common_baseline_|.
112  void CacheCommonFontHeightAndBaseline() const;
113
114  // Extracts font style and size into |font_style_| and |font_size_|.
115  void CacheFontStyleAndSize() const;
116
117  // A vector of Font. If FontList is constructed with font description string,
118  // |fonts_| is not initialized during construction. Instead, it is computed
119  // lazily when user asked to get the font vector.
120  mutable std::vector<Font> fonts_;
121
122  // A string representing font names, styles, and sizes.
123  // Please refer to the comments before class declaration for details on string
124  // format.
125  // If FontList is constructed with a vector of font,
126  // |font_description_string_| is not initialized during construction. Instead,
127  // it is computed lazily when user asked to get the font description string.
128  mutable std::string font_description_string_;
129
130  // The cached common height and baseline of the fonts in the font list.
131  mutable int common_height_;
132  mutable int common_baseline_;
133
134  // Cached font style and size.
135  mutable int font_style_;
136  mutable int font_size_;
137};
138
139}  // namespace gfx
140
141#endif  // UI_GFX_FONT_LIST_H_
142