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
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
|
---
title: Font Icons
order: 8
layout: page
---
[[themes.fonticon]]
= Font Icons
*_This section has not yet been updated for Vaadin Framework 8._*
Font icons are icons included in a font. Fonts have many advantages over bitmap
images. Browsers are usually faster in rendering fonts than loading image files.
Web fonts are vector graphics, so they are scalable. As font icons are text
characters, you can define their color in CSS by the regular foreground color
property.
[[themes.fonticon.enabling]]
== Loading Icon Fonts
Vaadin currently comes with one custom icon font: FontAwesome. It is
automatically enabled in the Valo theme. For other themes, you need to include
it with the following line in your project theme, after importing the base
theme:
----
@include fonticons;
----
If you use other icon fonts, as described in <<themes.fonticon.custom>>, and the
font is not loaded by a base theme, you need to load it with a
`font` mixin in Sass, as described in
<<themes-fonts#themes.fonts.loading,"Loading Local Fonts">>.
[[themes.fonticon.using]]
== Basic Use
Font icons are resources of type [classname]#FontIcon#, which implements the
[interfacename]#Resource# interface. You can use these special resources for
component icons and such, but not as embedded images, for example.
Each icon has a Unicode codepoint, by which you can use it. Vaadin includes an
awesome icon font, [literal]#++FontAwesome++#, which comes with an enumeration
of all the icons included in the font.
Most typically, you set a component icon as follows:
[source, Java]
----
TextField name = new TextField("Name");
name.setIcon(FontAwesome.USER);
layout.addComponent(name);
// Button allows specifying icon resource in constructor
Button ok = new Button("OK", FontAwesome.CHECK);
layout.addComponent(ok);
----
See the http://demo.vaadin.com/book-examples-vaadin7/book#themes.fonticon.basic[on-line example, window="_blank"].
The result is illustrated in <<figure.themes.fonticon.using>>, with the color
styling described next.
[[figure.themes.fonticon.using]]
.Basic Use of Font Icons
image::img/fonticons-basic.png[]
[[themes.fonticon.using.css]]
=== Styling the Icons
As font icons are regular text, you can specify their color with the
[literal]#++color++# attribute in CSS to specify the foreground text color. All
HTML elements that display icons in Vaadin have the [literal]#++v-icon++# style
name.
----
.v-icon {
color: blue;
}
----
If you use the font icon resources in other ways, such as in an
[classname]#Image# component, the style name will be different.
[[themes.fonticon.html]]
== Using Font icons in HTML
You can use font icons in HTML code, such as in a [classname]#Label#, by
generating the HTML to display the icon with the [methodname]#getHtml()# method.
[source, Java]
----
Label label = new Label("I " +
FontAwesome.HEART.getHtml() + " Vaadin",
ContentMode.HTML);
label.addStyleName("redicon");
layout.addComponent(label);
----
See the http://demo.vaadin.com/book-examples-vaadin7/book#themes.fonticon.html[on-line example, window="_blank"].
The HTML code has the [stylename]#v-icon# style, which you can modify in CSS:
[source, css]
----
.redicon .v-icon {
color: red;
}
----
See the http://demo.vaadin.com/book-examples-vaadin7/book#themes.fonticon.html[on-line example, window="_blank"].
The result is illustrated in <<figure.themes.fonticon-html.label>>, with the color
styling described next.
// The ID may not end in ".html"
[[figure.themes.fonticon-html.label]]
.Using Font Icons in Label
image::img/fonticons-html.png[]
You could have set the font color in the label's HTML code as well, or for all
icons in the UI.
You can easily use font icons in HTML code in other ways as well. You just need
to use the correct font family and then use the hex-formatted Unicode codepoint
for the icon. See for example the implementation of the [methodname]#getHtml()#
method in [classname]#FontAwesome#:
----
@Override
public String getHtml() {
return "<span class=\"v-icon\" style=\"font-family: " +
getFontFamily() + ";\">&#x" +
Integer.toHexString(codepoint) + ";</span>";
}
----
See the http://demo.vaadin.com/book-examples-vaadin7/book#themes.fonticon.html[on-line example, window="_blank"].
[[themes.fonticon.anywhere]]
== Using Font Icons in Other Text
You can include a font icon in any text by its Unicode codepoint, which you can
get with the [methodname]#getCodePoint()# method. In such case, however, you
need to use the same font for other text in the same string as well. The
FontAwesome provided in Vaadin includes a basic character set.
----
TextField amount = new TextField("Amount (in " +
new String(Character.toChars(
FontAwesome.BTC.getCodepoint())) +
")");
amount.addStyleName("awesomecaption");
layout.addComponent(amount);
----
See the http://demo.vaadin.com/book-examples-vaadin7/book#themes.fonticon.intext[on-line example, window="_blank"].
You need to set the font family in CSS.
----
.v-caption-awesomecaption .v-captiontext {
font-family: FontAwesome;
}
----
See the http://demo.vaadin.com/book-examples-vaadin7/book#themes.fonticon.intext[on-line example, window="_blank"].
[[themes.fonticon.custom]]
== Custom Font Icons
You can easily use glyphs in existing fonts as icons, or create your own.
[[themes.fonticon.custom.creating]]
=== Creating New Icon Fonts With IcoMoon
You are free to use any of the many ways to create icons and embed them into
fonts. Here, we give basic instructions for using the
link:http://icomoon.io/app/[IcoMoon] service, where you can pick icons from a
large library of well-designed icons.
Font Awesome is included in IcoMoon's selection of icon libraries. Note that the
codepoints of the icons are not fixed, so the [classname]#FontAwesome# enum is
not compatible with such custom icon fonts.
After you have selected the icons that you want in your font, you can download
them in a ZIP package. The package contains the icons in multiple formats,
including WOFF, TTF, EOT, and SVG. Not all browsers support any one of them, so
all are needed to support all the common browsers. Extract the [filename]#fonts#
folder from the package to under your theme.
See <<dummy/../../../framework/themes/themes-fonts#themes.fonts.loading,"Loading
Local Fonts">> for instructions for loading a custom font.
ifdef::web[]
[[themes.fonticon.custom.implementing]]
=== Implementing FontIcon
You can define a font icon for any font available in the browser by implementing
the [interfacename]#FontIcon# interface. The normal pattern for implementing it
is to implement an enumeration for all the symbols available in the font. See
the implementation of [classname]#FontAwesome# for more details.
You need a FontIcon API for the icons. In the following, we define a font icon
using a normal sans-serif font built-in in the browser.
----
// Font icon definition with a single symbol
public enum MyFontIcon implements FontIcon {
EURO(0x20AC);
private int codepoint;
MyFontIcon(int codepoint) {
this.codepoint = codepoint;
}
@Override
public String getMIMEType() {
throw new UnsupportedOperationException(
FontIcon.class.getSimpleName()
+ " should not be used where a MIME type is needed.");
}
@Override
public String getFontFamily() {
return "sans-serif";
}
@Override
public int getCodepoint() {
return codepoint;
}
@Override
public String getHtml() {
return "<span class=\"v-icon\" style=\"font-family: " +
getFontFamily() + ";\">&#x" +
Integer.toHexString(codepoint) + ";</span>";
}
}
----
See the http://demo.vaadin.com/book-examples-vaadin7/book#themes.fonticon.custom[on-line example, window="_blank"].
Then you can use it as usual:
----
TextField name = new TextField("Amount");
name.setIcon(MyFontIcon.EURO);
layout.addComponent(name);
----
See the http://demo.vaadin.com/book-examples-vaadin7/book#themes.fonticon.custom[on-line example, window="_blank"].
You could make the implementation a class as well, instead of an enumeration, to
allow other ways to specify the icons.
endif::web[]
|
