From 797157fe95c6b4ee2fd4e30534dfb492e60d8d6d Mon Sep 17 00:00:00 2001 From: Erik Lumme Date: Tue, 12 Sep 2017 16:37:44 +0300 Subject: [PATCH] Migrate UsingFontIcons --- .../articles/UsingFontIcons.asciidoc | 188 ++++++++++++++++++ documentation/articles/contents.asciidoc | 1 + 2 files changed, 189 insertions(+) create mode 100644 documentation/articles/UsingFontIcons.asciidoc diff --git a/documentation/articles/UsingFontIcons.asciidoc b/documentation/articles/UsingFontIcons.asciidoc new file mode 100644 index 0000000000..81bd3ea075 --- /dev/null +++ b/documentation/articles/UsingFontIcons.asciidoc @@ -0,0 +1,188 @@ +[[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 "&#x" + + Integer.toHexString(codepoint) + ";"; +  } + +  @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 `.` stylename, so you can +apply styles to only font icons (not ‘regular’ image icons): + +[source,css] +.... +.v-button .FontAwesome { + color: blue; +} +.... diff --git a/documentation/articles/contents.asciidoc b/documentation/articles/contents.asciidoc index 3c4808e885..396e4dfc3b 100644 --- a/documentation/articles/contents.asciidoc +++ b/documentation/articles/contents.asciidoc @@ -59,4 +59,5 @@ are great, too. - link:UsingVaadinCDIWithJAASAuthentication.asciidoc[Using Vaadin CDI with JAAS authentication] - link:LoadTestingWithGatling.asciidoc[Load testing with Gatling] - link:VaadinScalabilityTestingWithAmazonWebServices.asciidoc[Vaadin scalability testing with Amazon Web Services] +- link:UsingFontIcons.asciidoc[Using font icons in Vaadin 7.2] - link:CreatingAUIExtension.asciidoc[Creating a UI extension] -- 2.39.5