Icons are small, rectangular images/symbols that are referenced and displayed using controls such as the TIcon component. Elevate Web Builder uses a special control interface class called TIconLibrary to embed icons in a visual client application. The TIconLibrary control interface is stored in the TIconLibrary.wbi interface file included with the standard control interfaces provided with Elevate Web Builder, and contains several default icons. You can make a copy of the TIconLibrary.wbi interface file and place it in your project source directory in order to customize the icons for your application. Please see the Opening the Icon Library for more information on how to save a copy of the default TIconLibrary control interface so that it can be customized.

Supported Icon Types

---

Elevate Web Builder supports two different kinds of icons in the icon library: raster image icons (PNG) and font icons. All icons in the client component library use font icons. Font icons are preferable to image icons because font icons are vectors, not raster images. This means that they can be resized without losing any clarity, which is very important with very high display resolutions such as those used with the Retina displays available on Apple devices. Raster images, on the other hand, tend to look blurry as the image pixels are stretched and compressed to fit the current scale of the browser and the underlying display resolution. Even if you aren't targeting high-resolution displays, you will want your icons to look crisp and clear if the user zooms in/out using the built-in scaling available in most browsers. Another important consideration is that font icons are much smaller, overall, than the equivalent raster images. Finally, the fill color of font icons can be changed like any other font, whereas the colors of raster images are fixed. However, raster images allow for multiple colors in icons, which is not something that is currently supported with font icons.

Icon Fonts

---

Elevate Web Builder ships with an icon font called EWBIcons in both OpenType format and WOFF (web font) format. The OpenType version of the EWBIcons icon font is automatically installed during the Elevate Web Builder installation, and both formats are available in the \fonts subdirectory under the main installation directory.

The EWBIcons icon font is a trimmed-down version of the fantastic open source icon font called Font Awesome available here:

Font Awesome

With the EWBIcons icon font, the social media and brand icons were stripped from the original Font Awesome font in order to conserve space, and a few icons were added to support dataset toolbar navigation icons and the Elevate Web Builder "tool" logo icon. Because of this, the font name had to be changed from "FontAwesome" to "EWBIcons" in order to avoid any conflicts.

By default, all projects will include the EWBIcons icon font during compilation and embed it in the HTML loader file for the application. This behavior can be changed via the Build page of the Project Options for each project.

Defining Icons

---

Icons are represented in the states of the control interface, with the name of the icon corresponding to the state name. There are no limits to how many icons (states) one can define in the control interface. However, there are some rules that must be followed in order to allow the icons to appear correctly. The following lists the rules for both image icons and font icons:

Image Icons

• The base element for each icon (state) must be named "Icon".



• The "Icon" element's ApplyProperties Background property should be set to True.



• The icon image should be assigned using the "Icon" element's Background Image Name property.



• The icon image itself should be sized according to your needs, but as a rule do not use icons larger than 256x256 pixels. The one exception to this rule is when defining an animated icon. Defining animated icons is discussed below.



• The icon image should normally be positioned as ptCenterCenter using the "Icon" element's background image PositionType property. The one exception to this rule is when defining an animated icon. Defining animated icons is discussed below.



• The icon image should be set to not repeat by setting the "Icon" element's background image RepeatStyle property to rsNone.

Font Icons

• The base element for each icon (state) must be named "Icon".



• The icon's base "Icon" element should have a child element named "FontIcon".



• The "FontIcon" element's ApplyProperties AutoSize, Content, Font, FontColor, FontSize, Layout, and Padding properties should be set to True.



• The "FontIcon" element's AutoSize property should be set to True.



• The "FontIcon" element's Font Name property should be set to "EWBIcon", or the name of another icon font that you wish to use.



• The "FontIcon" element's Font Color and Size properties should be set according to your needs. The Font Style property is not normally used with font icons.



• The "FontIcon" element's Layout Position property should normally be set to lpCenter, but you can use any layout that you wish for the font icon.



• The "FontIcon" element's Padding property can be used to adjust the padding around the font icon. This is useful in cases where the font icon is getting cut off due to leading/trailing measurement issues with the font.

Defining Animated Icons

---

Animated icons are image icons whose background image isn't a small square or rectangle, but is instead a single image containing many different animation frames oriented in a single horizontal or vertical direction. These icons are referenced and displayed using controls such as the TAnimatedIcon component. In addition to the above rules for normal icons, there are also some rules that must be followed in order to allow animated icons to appear correctly:

• Contrary to normal icons, an animated icon image should always be positioned as ptSpecified using the "Icon" element's background image PositionType property.

Controls such as the TAnimatedIcon control use the background image's BeginAnimation method to animate the background image's Left or Top property (depending upon the orientation passed to the method), and the CancelAnimation method to stop any background image animation.

Loading Icons from Code

---

At both design-time and run-time, a global instance of the TIconLibrary class called IconLibrary is created that manages this special icon library control interface. The TIconLibrary class and the global IconLibrary instance can be found in the WebUI unit. Controls such as the TIcon control use this global instance to retrieve the list of available icons using the GetIconNames method, as well as apply an icon to one or more of its owned interface elements using the ApplyIcon method.