README.md
1QtAwesome - Font Awesome support for Qt applications
2====================================================
3
4Description
5-----------
6
7QtAwesome is a simple library that can be used to add [Font Awesome](http://fortawesome.github.io/Font-Awesome/) icons to your [Qt application](http://qt-project.org/).
8
9NOTE: Though the name is QtAwesome and currently it's very Font Awesome based, you can use every other icon/glyph font you want.
10
11The class can also be used to manage your own dynamic code-drawn icons, by adding named icon-painters.
12
13
14Updated to FontAwesome 4
15------------------------
16
17This library has been updated to Font Awesome version 4.
18
19The current Font Awesome version is **4.3.0**.
20
21* You can find the previous FontAwesome 4 c++11 library in the [c++11 branch](https://github.com/gamecreature/QtAwesome/tree/c++11).
22* You can find the previous FontAwesome 3 library in the [fontawesome-3 branch](https://github.com/gamecreature/QtAwesome/tree/fontawesome-3).
23
24
25**Note about previous c++11**
26
27I removed the C++11 requirement. And moved the c++11 code to a c++11 branch.
28It's not that I don't like c++11, but the typed enum made the code less flexible then it is now.
29Just integers it is. Simpeler is better.
30
31
32
33
34Installation
35------------
36
37The easiest way to include QtAweome in your project is to copy the QtAwesome directory to your
38project tree and add the following `include()` to your Qt project file:
39
40 include(QtAwesome/QtAwesome.pri)
41
42Now you are good to go!
43
44
45Usage
46-----
47
48You probably want to create a single QtAwesome object for your whole application:
49
50````
51 QtAwesome* awesome = new QtAwesome( qApp )
52 awesome->initFontAwesome(); // This line is important as it loads the font and initializes the named icon map
53
54````
55
56* Add an accessor to this object (i.e. a global function, member of your application object, or whatever you like).
57* Use an icon name from the [Font Awesome Cheatsheet](http://fortawesome.github.io/Font-Awesome/cheatsheet/).
58
59
60Example
61--------
62
63```c++
64// You should create a single object of QtAwesome.
65QtAwesome* awesome = new QtAwesome( qApp );
66awesome->initFontAwesome();
67
68// Next create your icon with the help of the icon-enumeration (no dashes):
69QPushButton* beerButton new QPushButton( awesome->icon( fa::beer ), "Cheers!" );
70
71// You can also use 'string' names to access the icons. (The string version omits the 'fa-' or 'icon-' prefix and has no dashes )
72QPushButton* coffeeButton new QPushButton( awesome->icon( "coffee" ), "Black please!" );
73
74// When you create an icon you can supply some options for your icons:
75// The available options can be found at the "Default options"-section
76
77QVariantMap options;
78options.insert( "color" , QColor(255,0,0) );
79QPushButton* musicButton = new QPushButton( awesome->icon( fa::music, options ), "Music" );
80
81// You can also change the default options.
82// for example if you always would like to have green icons you could call)
83awesome->setDefaultOption( "color-disabled", QColor(0,255,0) );
84
85// You can also directly render a label with this font
86QLabel* label = new QLabel( QChar( fa::group ) );
87label->setFont( awesome->font(16) );
88
89```
90
91Example custom painter
92----------------------
93
94This example registers a custom painter for supporting a duplicate icon (it draws 2 "plus marks"):
95
96```c++
97class DuplicateIconPainter : public QtAwesomeIconPainter
98{
99public:
100 virtual void paint( QtAwesome* awesome, QPainter* painter, const QRect& rectIn, QIcon::Mode mode, QIcon::State state, const QVariantMap& options )
101 {
102 int drawSize = qRound(rectIn.height()*0.5);
103 int offset = rectIn.height() / 4;
104 QChar chr = QChar( static_cast<int>(fa::plus) );
105
106 painter->setFont( awesome->font( drawSize ) );
107
108 painter->setPen( QColor(100,100,100) );
109 painter->drawText( QRect( QPoint(offset*2, offset*2), QSize(drawSize, drawSize) ), chr , QTextOption( Qt::AlignCenter|Qt::AlignVCenter ) );
110
111 painter->setPen( QColor(50,50,50) );
112 painter->drawText( QRect( QPoint(rectIn.width()-drawSize-offset, rectIn.height()-drawSize-offset), QSize(drawSize, drawSize) ), chr , QTextOption( Qt::AlignCenter|Qt::AlignVCenter ) );
113
114 }
115};
116
117awesome->give("duplicate", new DuplicateIconPainter() );
118```
119
120
121Default options:
122----------------
123
124 The following options are default in the QtAwesome class.
125
126```c++
127setDefaultOption( "color", QColor(50,50,50) );
128setDefaultOption( "color-disabled", QColor(70,70,70,60));
129setDefaultOption( "color-active", QColor(10,10,10));
130setDefaultOption( "color-selected", QColor(10,10,10));
131
132setDefaultOption( "text", QString() ); // internal option
133setDefaultOption( "text-disabled", QString() );
134setDefaultOption( "text-active", QString() );
135setDefaultOption( "text-selected", QString() );
136
137setDefaultOption( "scale-factor", 0.9 );
138```
139
140 When creating an icon, it first populates the options-map with the default options from the QtAwesome object.
141 After that the options are expanded/overwritten by the options supplied to the icon.
142
143 It is possible to use another glyph per icon-state. For example to make an icon-unlock symbol switch to locked when selected,
144 you could supply the following option:
145
146```c++
147 options.insert("text-selected", QString( fa::lock ) );
148```
149
150License
151-------
152
153MIT License. Copyright 2013 - Reliable Bits Software by Blommers IT. [http://blommersit.nl/](http://blommersit.nl)
154
155The Font Awesome font is licensed under the SIL Open Font License - [http://scripts.sil.org/OFL](http://scripts.sil.org/OFL)
156The Font Awesome pictograms are licensed under the CC BY 3.0 License - [http://creativecommons.org/licenses/by/3.0/](http://creativecommons.org/licenses/by/3.0/)
157"Font Awesome by Dave Gandy - http://fortawesome.github.com/Font-Awesome"
158
159Contact
160-------
161
162* email: <rick@blommersit.nl>
163* twitter: [https://twitter.com/gamecreature](https://twitter.com/gamecreature)
164* website: [http://blommersit.nl](http://blommersit.nl) (warning Dutch content ahead)
165* github: [https://github.com/gamecreature/QtAwesome](https://github.com/gamecreature/QtAwesome)
166
167Remarks
168-------
169
170I've created this project because I needed some nice icons for my own Qt project. After doing a lot of
171css/html5 work and being spoiled by the ease of twitter bootstrap with Font Awesome,
172I thought it would be nice to be able to use these icons for my Qt project.
173
174I've slightly changed the code from the original, added some more documentation, but it's still
175a work in progress. So feel free to drop me an e-mail for your suggestions and improvements!
176
177There are still some things todo, like:
178
179 * document the usage of another icon font
180 * add some tests
181 * do some code cleanup
182
183Thanks go to the contributors of this project!
184
185And of course last but not least,
186
187Many thanks go to Dave Gandy an the other Font Awesome contributors!! [http://fortawesome.github.com/Font-Awesome](http://fortawesome.github.com/Font-Awesome)
188And of course to the Qt team/contributors for supplying this great cross-platform c++ library.
189
190Contributions are welcome! Feel free to fork and send a pull request through Github.
191