Skip to content
This repository has been archived by the owner on Jun 23, 2022. It is now read-only.

Latest commit

 

History

History
270 lines (198 loc) · 10.8 KB

README.md

File metadata and controls

270 lines (198 loc) · 10.8 KB
Raw

This library is no longer maintained due to underlying issues.

Iconic Header

Travis codecov Pod Version Pod Platforms Swift Version License

Iconic helps making icon fonts integration effortless on iOS, tvOS and watchOS. Its main component is in charge of auto-generating strongly typed Swift code with SwiftGen, compatible with Objective-C.

You will interact with an auto-generated class under the name of {FontName}Icon.swift, which is a light abstraction of the IconDrawable.swift protocol. For more information, have a look at how to install and how to use.

Give Iconic a test drive by simply doing pod try Iconic in your terminal, and pick the Samples.xcworkspace.

Scale Example

Why Icon Fonts?

  • Resolution independent: scale and tint without quality loss
  • Automatically scaled for different screen densities
  • Work with (way) less image files
  • Improve visual consistency
  • Platform agnostic
  • Add better UI accessibility
  • Simple to work with

Where can I find awesome icon fonts?

Key Features

Note: Some open sourced icon fonts don't include the names of each of their glyphs. This could result in a non-descriptive enums, which can make things less intuitive for you when using Iconic. If you create your own icon font, make sure to properly name each glyph.

Installation

Via CocoaPods

Start by defining Iconic on your Podfile. Because we use an environment variable on a non-traditional setup, you will need to do it the following way:

pod 'Iconic', :git => 'https://github.com/home-assistant/Iconic.git', :tag => '1.3'

To install Iconic with a custom icon font, you need to use the FONT_PATH environment variable:

FONT_PATH='/Users/WillFerrell/Desktop/super-duper-font.otf' pod install

FONT_PATH='/Users/WillFerrell/Desktop/super-duper-font.otf' pod update Iconic

If you simply call pod install, Iconic will be installed using its default font, FontAwesome.

After the installation is complete, you should see 3 files: IconDrawable.swift, the auto-generated {FontName}Icon.swift and the font file added as a resource: Pod Setup

How to use

For complete documentation, visit Iconic's docs.

Import

Import the Iconic module:

Swift 
import Iconic
Objective-C 
@import Iconic;

Registering the icon font

Registration is required to activate Iconic. You shall do this once, when launching your application. Internally, the icon mapping is retrieved and kept in memory during the application's life term.

Iconic provides a convenient way to register the icon font: Note: the method name may change depending of your icon font's name:

Swift 
FontAwesomeIcon.register()
Objective-C 
[Iconic registerFontAwesomeIcon];

Use as images

You can construct an UIImage instance out of a font's icon and tint it. This may be very convenient for integrating with existing UIKit controls which expect UIImage objects already.

Images are created using NSStringDraw APIs to render a UIImage out of an NSAttributedString.

Swift 
let size = CGSize(width: 20, height: 20)

let icon = FontAwesomeIcon.HomeIcon
let image = icon.image(ofSize: size, color: .blue)
Objective-C 
[Iconic imageWithIcon:FontAwesomeIconHomeIcon size:CGSizeMake(20, 20) color:[UIColor blueColor]];

Use as attributed strings

You may need to icons as text too, and simplify your layout work. For example, instead of having an image and a label, you can combined it all in one single label:

Swift 
let icon = FontAwesomeIcon.HomeIcon
let iconString = icon.attributedString(ofSize: 20, color: .blue)
Objective-C 
[Iconic attributedStringWithIcon:FontAwesomeIconHomeIcon pointSize:20.0 color:[UIColor blueColor]];

Use as unicode string

Ultimately, you may need to retrieve the unicode string representation on an icon to do more advanced things:

Swift 
let unicode = FontAwesomeIcon.HomeIcon.unicode

Use as font

For further customization, you may need to use the UIFont object instead:

Swift 
let font = FontAwesomeIcon.font(ofSize: 20)
Objective-C 
UIFont *font = [Iconic fontAwesomeIconFontOfSize:20.0];

Interface Builder Support

Interface Builder

Iconic includes a UIImageView subclass under the name of {FontName}IconView.swift, conforming to @IBInspectable. This class allows IB integration with little effort:

  • Use the iconName attribute to set the icon on Interface Builder (use the icon font html catalog as reference for icon names).
  • Adjust the bounds of the view to see it dynamically adjust the icon size.

UIKit Extensions

UIKit extensions are also included, just to make your code look simpler:

Swift 
// UITarbBarItem
UITabBarItem(withIcon: .BookIcon, size: CGSize(width: 20, height: 20), title: "Catalog")

// UIBarButtonItem
UIBarButtonItem(withIcon: .BookIcon, size: CGSize(width: 24, height: 24), target: self, action: #selector(didTapButton))

// UIButton
let button = UIButton(type: .System)
button.setIconImage(icon: .HeartIcon, size: CGSize(width: 44, height: 44), color: nil, forState: .Normal)
Objective-C 
// UITarbBarItem
[[UITabBarItem alloc] initWithIcon:FontAwesomeIconBookIcon size:CGSizeMake(20.0, 20.0) title:@"Catalog"];

// UIBarButtonItem
[[UIBarButtonItem alloc] initWithIcon:FontAwesomeIconCogIcon size:CGSizeMake(24.0, 24.0) target:self action:@selector(didTapButton)];

// UIButton
UIButton *button = [UIButton buttonWithType:UIButtonTypeSystem];
[button setIconImageWithIcon:FontAwesomeIconHeartIcon size:CGSizeMake(44.0, 44.0) color:nil forState:UIControlStateNormal];

Sample Project

Check out the sample project, everything is demo'd there. Sample Project

Give Iconic a test drive by simply doing pod try Iconic in your terminal, and pick the Samples.xcworkspace.

On the sample project, Iconic is installed as a development pod. Because of this, pod files are not versioned. Therefore, if you clone the repo manually, you will to install the pods yourself.

About watchOS support:

When running the watchOS example, you might get a "No such module CoreText" error. This is because the CoreText.framework is missing for the watchOS Simulator. Run the 'WatchSimulator-CoreText-Patch.sh' script located in this repository, to copy the CoreText header files from the WatchOS SDK. You will then be able to run the watchOS sample with no issues as well as running Iconic on your Watch apps in the simulator.

Icon Font Catalog

Besides the auto-generated Swift code, an icon font catalog will be added in Pods/Iconic/Source/Catalog. Use this as a visual reference about the icons and their names.

Icon Font Catalog

Note: if you are using Chrome as your default browser, you will need to restart it using the open -a 'Google Chrome' --args -allow-file-access-from-files in the command line to be able to open view the catalog. This is because the html's javascript loads a local json file and Chrome has built-in security features to disable it. You can also use any other web browser like Safari or Firefox to open the catalog html.

Icon Font Samples

This repository also includes a few open source and free icon fonts for you to try Iconic with:

Acknowledgements

Iconic was originally developed by Ignacio Romero Zurbuchen. For more credits, please see AUTHORS.md.

License

This library is licensed under the Apache 2.0 license.

SwiftGen is licensed under the MIT License.

The Font Awesome font is licensed under the SIL OFL 1.1 License