forked from restitux/mumble-wiki-export
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Skinning.html
293 lines (242 loc) · 14.2 KB
/
Skinning.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
<p>{{Notice</p>
<table>
<tr>
<td>message=If you are using Mumble 1.3+, please refer to <a href="Themes">Themes</a> instead.</td>
</tr>
</table>
<p>}}</p>
<p>Note: This is not a complete tutorial; [https://www.google.com Google] is your friend. Please edit this page if you find a feature or step you think should be included; it's a wiki for a reason!</p>
<p>'''ALL SKINNERS NOTE: You can convert many of your PNGs to SVGs using Inkscape; click <a href="Skinning#Converting_PNG_to_SVG">here</a> for instructions.'''</p>
<h2>Introduction</h2>
<p>The look of Mumble can be customized by using so called Qt Style Sheets (short QSS). These are very similar to cascading style sheets (CSS) used in web development. So if you have any experience with these you will instantly feel at home.</p>
<p>If you do not have any experience with CSS that is not a problem either. We will try to explain the basic aspects of skinning in this article.</p>
<p>For the purpose of avoiding confusion, we will use one skin in this entire guide, named ''Chocolate''.</p>
<p>Let us start off by realizing that creating a skin for Mumble is not hard, but it ''does'' take time and patience. Before asking other people what to do, try googling! It really, really works! </p>
<p>Now, here is an explanation of the exact layout of a Mumble skin. </p>
<p>First, in order to use a skin, you must have a ''skins'' folder inside of Program Files\Mumble. Inside of the ''skins'' folder, you will need to create another folder; this folder will be your skin's name. For example, if you wanted to create a skin named "Chocolate", then you would have the following directory structure:<br />
C:\Program Files\Mumble\skins\Chocolate<br />
And here is what is inside this ''Chocolate'' folder:<br />
actions/audio-input-microphone.svg<br />
actions/media-record.svg<br />
categories/applications-internet.svg <br />
emblems/emblem-favorite.svg *<br />
places/network-workgroup.svg <br />
Chocolate.qss<br />
authenticated.svg<br />
channel.svg<br />
channel_active.svg<br />
channel_linked.svg<br />
comment.svg<br />
comment_seen.svg<br />
config_asio.png<br />
config_basic.png<br />
config_dsound.png<br />
config_lcd.png<br />
config_msgs.png<br />
config_network.png<br />
config_osd.png<br />
config_plugin.png<br />
config_shortcuts.png<br />
config_ui.png<br />
deafened_self.svg<br />
deafened_server.svg<br />
Information_icon.svg<br />
layout_classic.svg<br />
layout_custom.svg<br />
layout_hybrid.svg<br />
layout_stacked.svg<br />
mumble.osx.png<br />
mumble.svg<br />
muted_local.svg<br />
muted_self.svg<br />
muted_server.svg<br />
muted_suppressed.svg<br />
rec.svg<br />
self_undeafened.svg<br />
deafened_self.svg<br />
talking_alt.svg<br />
talking_off.svg<br />
talking_on.svg<br />
talking_whisper.svg </p>
<ul>
<li>Note that emblem-favorite.svg is also the friend icon.If you want to look at any of these icons, you can find them [https://github.com/mumble-voip/mumble/tree/master/icons here].</li>
</ul>
<p>But this is all a skin is. It is ''one'' file that contains the coding elements of the skin (Chocolate.qss) - the code that defines the color of the background, the fonts, etc. - and then the images that Mumble uses. '''Any of the images listed above are autoloaded by simply placing them in ''Program Files\Mumble\skins\Chocolate, or the correct subdirectories listed'''''.</p>
<p>Here are images that can be defined in the QSS:<br />
arrow_down.png <br />
arrow_left.png <br />
arrow_right.png arrow_*.png dimensions: 7x7<br />
arrow_up.png <br />
branch.png<br />
branch_closed.png <br />
branch_end.png branch_*.png dimensions: 10x18<br />
branch_more.png<br />
branch_open.png<br />
checkbox_0.png<br />
checkbox_0_d.png<br />
checkbox_0_hover.png<br />
checkbox_0_hover_d.png<br />
checkbox_0_pressed.png<br />
checkbox_1.png checkbox_*.png dimensions: 13x13<br />
checkbox_1_d.png<br />
checkbox_1_hover.png<br />
checkbox_1_hover_d.png<br />
checkbox_1_pressed.png<br />
radiobutton_0.png<br />
radiobutton_0_hover.png<br />
radiobutton_0_pressed.png<br />
radiobutton_1.png radiobutton_*.png dimensions: 13x13<br />
radiobutton_1_hover.png<br />
radiobutton_1_pressed.png </p>
<p>You should be able to use SVGs instead of PNGs for these images, if you so wish.</p>
<h2>Explanation and Usage of SVG</h2>
<p>"Scalable Vector Graphics (SVG) is a family of specifications of an XML-based file format for describing two-dimensional vector graphics, both static and dynamic (i.e. interactive or animated)" ([http://en.wikipedia.org/wiki/Scalable_Vector_Graphics Wikipedia]). Basically, these are ''not'' binary images. An application reads them, and then turns them into an image. They are simply large text files. Because of this, however, they scale tremendously well...from tiny icons to images the size of your entire screen. Mumble now primarily uses SVG, although there are still some images in the PNG format.</p>
<p>In order to create an SVG file, you need a SVG creator. The best one is probably [http://www.inkscape.org/ Inkscape]. A big problem at the moment is that most people are foreign to SVG creation. However, SVG creation with Inkscape is not hard, and you probably will have quite a bit of fun with it. Remember that in SVG, there are no dimensions. Everything is scalable.</p>
<p>'''You should use the ''svgtiny'' format for your SVG file. If you are using Inkscape, save it as a "Plain SVG".'''</p>
<h2>Converting PNG to SVG</h2>
<p>Note that while many PNG images can be converted, your mileage may vary.</p>
<ol>
<li>Start [http://www.inkscape.org/ Inkscape]</li>
<li>Open the .png</li>
<li>Go to Effects -> Images -> Embed All Images...</li>
<li>Click OK</li>
<li>Save image as "Plain SVG".</li>
<li>Implement SVG image in your skin</li>
</ol>
<h2>Creating a Mumble Skin</h2>
<p>[http://doc.qt.io/qt-5/stylesheet-reference.html Here] is an excellent guide that explains the structure of Qt skinning, and how to specify a certain property or element of a class. </p>
<h3>QSS Files</h3>
<p>Qt Style Sheets draw heavily from the syntax used in Cascading Style Sheet (CSS) used in web development. If you have any experience with CSS this will be a big help.</p>
<p>From Configure -> Settings -> User Interface -> Skin, you can set the QSS file to use. This contains all of the code elements of the skin.</p>
<p>The basic structure of a QSS file may include:<br />
<code><br />
/* this is a comment */</p>
<p> QTreeView {<br />
background-color: white;<br />
color: black;<br />
}</p>
<p> QTextBrowser {<br />
background-color: #CCCCFF; /* 3 digit hex colors also acceptable: #CCF */<br />
}</p>
<p> QMenuBar {<br />
/* place more stuff here */<br />
}<br />
QMenu {<br />
/* place more stuff here */<br />
}<br />
</code><br />
You may use <code>background-color</code> and <code>color</code> like a [http://en.wikipedia.org/wiki/Cascading_Style_Sheets CSS] definition.</p>
<ul>
<li><code>QTreeView</code> refers to the channel/player area of Mumble.</li>
<li><code>QTextBrowser</code> refers to where messages are printed.</li>
<li><code>QMenuBar</code> and <code>QMenu</code> refers to the top menu.</li>
</ul>
<p>Note that you can use a shortened hex color key if the color is simple enough. For instance, to define white, you don't need to use #FFFFFF; simply use #FFF.</p>
<p>For more complex skinning, your QSS file should have more general elements, such as scrollbars, checkboxes, buttons, and text. It is recommended to refer to the [http://doc.qt.io/qt-5/stylesheet-syntax.html Qt Style Sheets Documentation] for this. For styling a particular part of Mumble, see <a href="Qt Structure">Qt Structure</a>.</p>
<p>Here's a little blob of QSS that will skin nearly everything in Mumble. It might help you in your skinning endeavors.</p>
<p><code><br />
QHeaderView::section {<br />
background: qlineargradient(x1:0, y1:0, x2:0, y2:1, stop:0 #fff, stop:1 #333);<br />
color: #333;<br />
border: 1px solid #333;<br />
border-color: #fff #333 #333 #fff;<br />
height: 1.54em;<br />
}<br />
QMainWindow#MainWindow * {<br />
background: qlineargradient(x1:0, y1:0, x2:0, y2:1, stop:0 #fff, stop:1 #333);<br />
}<br />
QMainWindow#MainWindow{<br />
background: qlineargradient(x1:0, y1:0, x2:0, y2:1, stop:0 #fff, stop:1 #333);<br />
border: 0;<br />
}<br />
QMenuBar {<br />
background: qlineargradient(x1:0, y1:0, x2:0, y2:1, stop:0 #fff, stop:1 #333);<br />
color: #333;<br />
font-weight: bold;<br />
border: 1px solid transparent;<br />
border-bottom-color: #333;<br />
}<br />
QMenuBar::item {<br />
background: transparent;<br />
color: #333;<br />
border: 0;<br />
}<br />
</code></p>
<h3>Finding Classes and Names</h3>
<p>The hardest part of creating a skin is probably just finding out ''what'' needs to be skinned. Thankfully, there is a fairly easy way to do this. First, you need to download a tarball of Mumble's source. Get it [https://github.com/mumble-voip/mumble/archive/master.zip here]. Extract it, then navigate to ''*\mumble\src\mumble''. </p>
<p>Now install [http://download.qt.io/official_releases/qtcreator Qt Creator]. Once it is installed, open the Explorer window that you started in the previous step. Now navigate to the *.ui files that seem to correlate to whatever part of Mumble you want to skin, and then open it. For example, if you wanted to skin the main window, then open MainWindow.ui. If it does not automatically open in Qt Creator, then right click the .ui file, select properties, then go to "open with" and navigate to ''C:\Qt\Tools\QtCreator\bin\qtcreator.exe''.</p>
<p>Now you can get a general idea of which classes and names you need to skin. For example, at the top right corner you can see the tree structure of the Qt. You see that the entire window of Mumble is grouped into the class "QMainWindow", and that the name of the entire Mumble window is "MainWindow". Therefore, if you wanted to skin all of it, you would use the following QSS:<br />
<code><br />
QMainWindow * {<br />
background-color: #000;<br />
}<br />
</code></p>
<p>Similarly, you can click on a component of a window that you open in Qt Designer, and it should highlight the class name at the top left. For instance, open ConfigDialog.ui. Click on the white, vertical box on the left. At the top left, you should see Designer highlight "qlwIcons QListWiget". From that, you know that you can skin this property using </p>
<p><code><br />
QListWidget#qlwIcons {<br />
attribute: value;<br />
}<br />
</code></p>
<p>then, you could define the actual components inside of this box. For example:</p>
<p><code><br />
QListWidget#qlwIcons::item {<br />
background: qlineargradient(x1:0, y1:0, x2:0, y2:1, stop:0 #fff, stop:1 #333);<br />
}<br />
</code></p>
<p>This will skin the items that are nested inside of this box (example: "Shortcuts").</p>
<p>If you want to skin this same item, when it is clicked, then you use</p>
<p><code><br />
QListWidget#qlwIcons::item:selected {<br />
background: qlineargradient(x1:0, y1:0, x2:0, y2:1, stop:0 #fff, stop:1 #333);<br />
}<br />
</code></p>
<h4>Toolbar Skinning</h4>
<p>Location of Icon in Toolbar</p>
<p> "applications-internet.svg" <small>-</small>>/icons/tango/categories/applications-internet.svg Connect<br />
"Information_icon.svg" ---->/icons/publicdomain/Information_icon.svg This is for Server info<br />
"self_undeafened.svg"<small>-</small>>/icons/self_undeafened.svg Un-muted Headset<br />
"deafened_self.svg" <small>-</small>>/icons/deafened_self.svg Muting Headset<br />
"comment.svg"---->/icons/comment.svg<br />
"audio-input-microphone.svg" <small>-</small>>/icons/tango/actions/audio-input-microphone.svg Microphone Un-muted<br />
"audio-input-microphone-muted.svg" <small>-</small>>/icons/tango/actions/audio-input-microphone-muted.svg Microphone muted</p>
<h4>Skinning the log</h4>
<p>In 1.2.1 the capability to specifically skin certain aspects of log messages was added. Following new QSS classes are available:<br />
Timestamps: log-time<br />
Servers: log-server<br />
Channels: log-channel<br />
Operation targets: log-target<br />
Operation sources: log-source<br />
Privileges: log-privilege<br />
Be aware that channels, targets and sources are links. Using them look like this:<br />
.log-time {<br />
color: blue;<br />
}</p>
<h3>Standards</h3>
<p>These are more recommendations than standards, but either way, it's here to reduce any confusion.</p>
<h4>Image Pointing</h4>
<p>If you use additional images not already defined by Mumble you should keep it within its own directory as described here. Here's an example of such a case:<br />
<code><br />
/* change the left arrow of the scrollbar */<br />
QScrollBar::left-arrow {<br />
image: url(skin:arrow_left.svg);<br />
}<br />
</code><br />
Notice the colon ":" means the current skin directory. So, the current directory is Chocolate's root directory (eg: "C:\Program Files\Mumble\skins\Chocolate"). Thus, the image is located at "C:\Program Files\Mumble\skins\Chocolate\arrow_left.png". Refer to the Qt Style Sheets Documentation, as previously linked, for more information.</p>
<p>This is assuming arrow_left.png is in the same directory as the current QSS file. If you had it in a "images" folder inside of your skin folder, then it would be<br />
<code><br />
/* change the left arrow of the scrollbar */<br />
QScrollBar::left-arrow {<br />
image: url(skin:images/arrow_left.svg);<br />
}<br />
</code></p>
<h4>Style</h4>
<p>It is recommended to use the "WindowsXP" or "WindowsVista" style for all skins. This is because it has the least cosmetic defects.</p>
<h2>See Also</h2>
<ul>
<li><a href="Skins">Skins</a> for a list of Skins</li>
<li>[http://doc.qt.io/qt-5/stylesheet-syntax.html Qt Style Sheet Syntax]</li>
<li>[http://doc.qt.io/qt-5/stylesheet-examples.html Qt Style Sheet Examples]</li>
<li>[http://doc.qt.io/qt-5/stylesheet-reference.html Qt Style Sheet Reference]</li>
</ul>
<p><a href="Category:Documentation English">Category:Documentation English</a><br />
<a href="Category:Contribution">Category:Contribution</a></p>