--- /dev/null
+[[using-font-icons-in-vaadin-7.2]]
+Using font icons in Vaadin 7.2
+------------------------------
+
+A “font icon” is an icon that is a glyph (essentially a character) from
+a font. A font that is made for this purpose (containing only icons) is
+called an “icon font”. Font icons scale well (being vectors), so you do
+not have to make icons for a specific pixel size. Icon fonts are also
+typically very light-weight (in bytes), and easy to use once set up.
+
+Vaadin 7.2 comes with generic support for font icons, and has the
+popular http://fortawesome.github.io/Font-Awesome/[FontAwesome] icon font
+built-in. The support is ‘generic’, in the sense that it does not
+include some of the advanced styling options specifically available in
+FontAwesome (such as spinning icons).
+
+FontAwesome is included in the theme by default, but the fonts are only
+loaded by the browser when used. If needed, you can also remove the CSS,
+minimize the font, or make a custom font.
+
+A demo application showing the result is
+https://github.com/Porotype/FontIconDemo[available onGitHub]
+(https://github.com/Porotype/FontIconDemo/tree/master/src/com/example/fonticondemo[java],
+https://github.com/Porotype/FontIconDemo/blob/master/WebContent/VAADIN/themes/fonticondemo/fonticondemo.scss[scss])
+
+[[using-fontawesome]]
+Using FontAwesome
+~~~~~~~~~~~~~~~~~
+
+You can use font icons with the familiar `setIcon()` method. It looks like
+this, when using the built-in FontAwesome:
+
+[source,java]
+....
+button.setIcon(FontAwesome.BOOKMARK);
+....
+
+You can also easily embed an icon in any place that allows HTML:
+
+[source,java]
+....
+label.setContentMode(ContentMode.HTML);
+label.setValue("Press " + FontAwesome.BOOKMARK.getHtml() + " to bookmark");
+....
+
+[[making-a-custom-set-of-icons]]
+Making a custom set of icons
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There are many tools for making icons, and icon fonts. One of our
+favourite tools is http://icomoon.io/app[IcoMoon], which is an excellent
+online application where you can pick icons from a vast library of
+ready-made icon fonts, to compose your own set of icons. When you’re
+done, you can download a zip that contains your font files - just copy
+the ‘fonts’ folder to your theme.
+
+1. Browse to http://icomoon.io/app
+2. _Add icons from library_ (the first time, some icons sets are added
+automatically)
+3. _Add_ the icon set(s) you fancy (notice the licenses)
+4. Mark the icons you want in your font
+5. _Download_ the font
+
+In IcoMoon you can also produce a customised version of FontAwesome, if
+you for instance want to remove unused icons, or swap individual icons.
+You can also re-upload your custom icon font, if you want to make
+changes or additions to it later.
+
+1. _Import icons_
+2. Add/delete/swap icons
+3. _Download_ the new font
+
+When using ready-made icons, please pay attention to the licenses the
+different icon sets have.
+
+[[using-a-custom-icon-font]]
+Using a custom icon font
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+To use your own icon set, you need to do four things:
+
+1. Make an icon font
+2. Make it easily usable from Java and
+3. Load the font in your theme
+4. Use the icons in your application.
+
+(You can skip #1 if you already have an icon font you want to use.)
+
+*1. Compose an icon font* in e.g IcoMoon, download, and copy the “fonts”
+folder from the zip to your theme.
+
+*2. Add the following to your styles.scss* OUTSIDE of the `.mytheme{}` block:
+
+[source,scss]
+....
+@include font(IcoMoon, '../../fonticondemo/fonts/icomoon');
+....
+
+The first parameter, “IcoMoon”, is the font-family - i.e the name you
+want to use for your font. You can choose anything, as long as you use
+the same name in Java later. +
+The second parameter is the filename base; in this case the files are
+called icomoon.ttf, icomoon.svg, etc...
+
+*3. Make use of the icons in Java;* you can make an anonymous FontIcon
+instance, but in practice you will probably want to make an enum or some
+sort of icon factory. The FontAwesome implementation uses an enum, in
+this manner:
+
+[source,java]
+....
+ private final int codepoint;
+
+ IcoMoon(int codepoint) {
+ this.codepoint = codepoint;
+ }
+
+ @Override
+ public String getFontFamily() {
+ // This must match the name you use in your (S)CSS
+ return "IcoMoon";
+ }
+
+ @Override
+ public int getCodepoint() {
+ return codepoint;
+ }
+
+ @Override
+ public String getHtml() {
+ return "<span class=\"v-icon IcoMoon\">&#x"
+ + Integer.toHexString(codepoint) + ";</span>";
+ }
+
+ @Override
+ public String getMIMEType() {
+ throw new UnsupportedOperationException("Not supported for FontIcon");
+ }
+....
+
+(Note that you can easily generate the enum from the list of icons in
+the zip downloaded from IcoMoon.)
+
+*4. Now you can use your icon:*
+
+[source,java]
+....
+ button.setIcon(IcoMoon.RIBBON);
+....
+
+[[styling-font-icons]]
+Styling font icons
+~~~~~~~~~~~~~~~~~~
+
+You can not generally set style names on the icon itself, instead you
+apply styles to the _component_ where the icon is used, much in the same
+way you would style anything else in a component.
+
+Given a button with a font icon and a style name:
+
+[source,java]
+....
+ button.addStyleName("redicon");
+ button.setIcon(FontAwesome.SAVE);
+....
+
+…you can then style the icon by applying styles to the .v-icon element:
+
+[source,css]
+....
+ .redicon .v-icon {
+ color: red;
+ font-size: 20px;
+ }
+....
+
+Note that the icon is actually text, so you style it in much the same
+way you style text.
+
+A font icon also gets an additional `.<font-family>` stylename, so you can
+apply styles to only font icons (not ‘regular’ image icons):
+
+[source,css]
+....
+.v-button .FontAwesome {
+ color: blue;
+}
+....
projects / vaadin-framework.git / commitdiff