Debian Codegraph @

modules/lsp-plugins-shared/src/doc/manuals/development/ui_guidelines.php

raw
1 <?php
2 $CTL = $RES_ROOT . "/img/ui_guidlines/";
3 ?>
4
5 <h2><a href="#foreword">Foreword</a></h2>
6 <p>Before introducing any changes to the user interface, it is very important to carefully consider their necessity and possible side effects. It is important to understand how these changes will affect end users and ensure that they won’t complicate
7 or disimprove the user experience.</p>
8 <p>It is also important to count that any changes in the user interface may require additional time spendings for development and testing. Also it is very important to estimate how these changes can make the final product better.</p>
9
10 <h2><a href="#terms">Common terms</a></h2>
11 <p>The main principle of the LSP Plugins’ user interface creation is the compactness. </p>
12 <p>Althroug plugins are present as standalone applications and built-in plugins for DAW, it is important to make the plugin window as compact as possible. It is needed to make the end user possible to simultaneously work with multiple plugins on the
13 same screen.</p>
14 <p>The main complexity of creation of the UI is that LSP Plugins, as usual, provide many controllable parameters available to the user. That gives wide tuning possibilities, higher precision and flexibility to the workflow, so all these controls
15 should be displayed in the plugin’s window.</p>
16 <p>In other words, it is important to find compromises between the compactness and the comfortability of the use.</p>
17
18 <h2><a href="#grid">Block and table system</a></h2>
19
20 <p>We use the mix of block and table system while developing the UI - this is a markup plinciple based on usage of tables and nested elements - widgets.<br />
21 Widget is a small interactive element which can provide different functions and act as some view of some information or some control which allows to modify some information.
22 </p>
23
24 <p>Widgets can be grouped into blocks and placed at some position of the table — such mmix of block and table markup allows to define the position and the structure of widgets in the plugin’s window.</p>
25
26 <h2><a href="#principles">Basic principles</a></h2>
27
28 <ul>
29 <li>The plugin’s window becomes split into separate blocks, each of them can contain it’s own properties: the color of the background, the padding, the minimal width, etc. The size of paddings, minimal size, etc is counted in nominal pixels.</li>
30 <li>Also block can be built-in into another block. This allows to create more complicated structures.</li>
31 <li>Blocks can inherit some features of parent blocks. For example, the color of the background.</li>
32 <li>We use tags for the definition of the window structure and location of the blocks.</li>
33 </ul>
34 <p>The example below demonstrates the markup of very simple interface for some plugin.</p>
35 <div class="grid-2col-man">
36 <div class="thc-descr">
37 <pre style="margin-top: 0px;">
38 &lt;plugin resizable=&quot;true&quot;&gt;
39 &nbsp;&nbsp;&lt;hbox bg.color=&quot;bg_schema&quot; pad.v=&quot;4&quot;&gt;
40 &nbsp;&nbsp;&nbsp;&nbsp;&lt;vbox spacing=&quot;4&quot;&gt;
41 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;label text=&quot;labels.signal.dry&quot;/&gt;
42 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;knob id=&quot;dry&quot; scale.color=&quot;dry&quot;/&gt;
43 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;value id=&quot;dry&quot;/&gt;
44 &nbsp;&nbsp;&nbsp;&nbsp;&lt;/vbox&gt;
45 &nbsp;&nbsp;&nbsp;&nbsp;&lt;vbox spacing=&quot;4&quot;&gt;
46 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;label text=&quot;labels.signal.wet&quot;/&gt;
47 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;knob id=&quot;wet&quot; scale.color=&quot;wet&quot;/&gt;
48 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;value id=&quot;wet&quot;/&gt;
49 &nbsp;&nbsp;&nbsp;&nbsp;&lt;/vbox&gt;
50 &nbsp;&nbsp;&nbsp;&nbsp;&lt;vbox spacing=&quot;4&quot;&gt;
51 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;label text=&quot;labels.output&quot;/&gt;
52 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;knob id=&quot;g_out&quot;/&gt;
53 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;value id=&quot;g_out&quot;/&gt;
54 &nbsp;&nbsp;&nbsp;&nbsp;&lt;/vbox&gt;
55 &nbsp;&nbsp;&lt;/hbox&gt;
56 &lt;/plugin&gt;</pre>
57 </div>
58 <div class="thc-descr">
59 <img class="plugin" style="max-width: 100%;" src="<?= $CTL ?>/simple_interface.png">
60 <p>And this is how this interface looks out.</p>
61 </div>
62 </div>
63 <ul>
64 <li>If the structure is more complicated than set of several blocks placed into one single horizontal or vertical line, it is recommended to use grid and place blocks and widgets into separate cells of the grid.</li>
65 </ul>
66 <div class="grid-2col-man">
67 <div class="thc-descr">
68 <pre style="margin-top: 0px;">&lt;plugin resizable=&quot;true&quot;&gt;
69 &nbsp;&nbsp;&lt;grid rows=&quot;3&quot; cols=&quot;3&quot; spacing=&quot;4&quot;
70 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp; bg.color=&quot;bg_schema&quot; pad.v=&quot;4&quot;&gt;
71 &nbsp;&nbsp;&nbsp;&nbsp;&lt;!-- Row 1 --&gt;
72 &nbsp;&nbsp;&nbsp;&nbsp;&lt;label text=&quot;labels.signal.dry&quot;/&gt;
73 &nbsp;&nbsp;&nbsp;&nbsp;&lt;label text=&quot;labels.signal.wet&quot;/&gt;
74 &nbsp;&nbsp;&nbsp;&nbsp;&lt;label text=&quot;labels.output&quot;/&gt;
75 &nbsp;&nbsp;&nbsp;&nbsp;&lt;!-- Row 2 --&gt;
76 &nbsp;&nbsp;&nbsp;&nbsp;&lt;knob id=&quot;dry&quot; scale.color=&quot;dry&quot;/&gt;
77 &nbsp;&nbsp;&nbsp;&nbsp;&lt;knob id=&quot;wet&quot; scale.color=&quot;wet&quot;/&gt;
78 &nbsp;&nbsp;&nbsp;&nbsp;&lt;knob id=&quot;g_out&quot;/&gt;
79 &nbsp;&nbsp;&nbsp;&nbsp;&lt;!-- Row 3 --&gt;
80 &nbsp;&nbsp;&nbsp;&nbsp;&lt;value id=&quot;dry&quot;/&gt;
81 &nbsp;&nbsp;&nbsp;&nbsp;&lt;value id=&quot;wet&quot;/&gt;
82 &nbsp;&nbsp;&nbsp;&nbsp;&lt;value id=&quot;g_out&quot;/&gt;
83 &nbsp;&nbsp;&lt;/grid&gt;
84 &lt;/plugin&gt;</pre>
85 </div>
86 <div class="thc-descr">
87 <img class="plugin" style="max-width: 100%;" src="<?= $CTL ?>/simple_interface_grid.png">
88 <p>At the first glance, the UI looks the same to the previous example. But actually the grid is much better dealing with the space allocation between widgets and their placing.</p>
89 </div>
90 </div>
91 <ul>
92 <li>We use schemas to define styles for block’s elements <b><em>(located in the following project’s relative path: lsp-plugins/modules/lsp-plugins-shared/res/main/schema)</em></b>, which contain predefined colors, widget properties and their
93 behavior. It is also possible to set widget attributes using tag’s attributes as we saw it in the example above with knob widgets: <b><em>&lt;knob id=&quot;dry&quot; scale.color=&quot;dry&quot; /&gt;</em></b>. <br /> Such markup allows to have
94 more flexible control over the location of elements within plugin’s window and make the overall UI design adaptive.</li>
95 <li>For better understanding of how does it all work together, it is better to perform the one’s own analysis of one of already designed plugins.</li>
96 </ul>
97
98 <h2><a href="#colors">Color and style schemes</a></h2>
99 <p>The style scheme includes all the information about what colors, paddings, sizes etc will be utilized by widgets.</p>
100 <div class="grid-2col-man">
101 <div class="thc-descr">
102 <p style="text-align:center">Preconfigured style in the Modern.xml schema:</p>
103 <span><img class="border" style="float: right; margin-left: 10px;" src="<?= $CTL ?>/modern_group.png">
104 <pre style="margin-top: 0px; max-width: 270px;">
105 &lt;style class=&quot;Group&quot; parents=&quot;root&quot;&gt;
106 &nbsp;&nbsp; &nbsp;&lt;color value=&quot;bg_name&quot;/&gt;
107 &nbsp;&nbsp; &nbsp;&lt;border.size value=&quot;0&quot;/&gt;
108 &nbsp;&nbsp; &nbsp;&lt;text.color value=&quot;text_group&quot;/&gt;
109 &nbsp;&nbsp; &nbsp;&lt;text.radius value=&quot;0&quot;/&gt;
110 &nbsp;&nbsp; &nbsp;&lt;ipadding value=&quot;6&quot;/&gt;
111 &nbsp;&nbsp; &nbsp;&lt;padding value=&quot;0&quot;/&gt;
112 &nbsp;&nbsp; &nbsp;&lt;border.radius value=&quot;0&quot;/&gt;
113 &nbsp;&nbsp; &nbsp;&lt;bg.color value=&quot;bg_light&quot;/&gt;
114 &nbsp;&nbsp; &nbsp;&lt;heading value=&quot;-1 1&quot;/&gt;
115 &nbsp;&nbsp; &nbsp;&lt;text.padding.left value=&quot;6&quot;/&gt;
116 &lt;/style&gt;</pre>
117 </span>
118
119 </div>
120
121 <div class="thc-descr">
122 <p style="text-align:center">Preconfigured style in the Legacy.xml schema:</p>
123 <span><img class="border" style="float: right; margin-left: 10px;" src="<?= $CTL ?>/legacy_group.png">
124 <pre style="margin-top: 0px; max-width: 260px;">
125 &lt;style class=&quot;Group&quot; parents=&quot;root&quot;&gt;
126 &nbsp;&nbsp; &nbsp;&lt;color value=&quot;bg_name&quot;/&gt;
127 &nbsp;&nbsp; &nbsp;&lt;border.size value=&quot;2&quot;/&gt;
128 &nbsp;&nbsp; &nbsp;&lt;text.color value=&quot;text_group&quot;/&gt;
129 &nbsp;&nbsp; &nbsp;&lt;text.radius value=&quot;10&quot;/&gt;
130 &nbsp;&nbsp; &nbsp;&lt;ipadding value=&quot;12&quot;/&gt;
131 &nbsp;&nbsp; &nbsp;&lt;padding value=&quot;0&quot;/&gt;
132 &nbsp;&nbsp; &nbsp;&lt;border.radius value=&quot;10&quot;/&gt;
133 &nbsp;&nbsp; &nbsp;&lt;bg.color value=&quot;bg&quot;/&gt;
134 &nbsp;&nbsp; &nbsp;&lt;heading value=&quot;-1 0&quot;/&gt;
135 &nbsp;&nbsp; &nbsp;&lt;text.padding.left value=&quot;6&quot;/&gt;
136 &lt;/style&gt;</pre>
137 </span>
138
139 </div>
140 </div>
141 <p>The user interface of LSP Plugins allows to use multiple schemas which can be switched in runtime (without need to reload) by using one of the menu items listed in the menu→visual schema menu.</p>
142 <p style="text-align:center">Scheme "Modern":</p>
143 <div class="images" style="margin: -10px auto 15px auto;">
144 <img class="border" style="max-width: 100%;" src="<?= $CTL ?>/scheme_modern.png">
145 </div>
146 <p style="text-align:center">Scheme "Legacy":</p>
147 <div class="images" style="margin: -10px auto 15px auto;">
148 <img class="border" style="max-width: 100%;" src="<?= $CTL ?>/scheme_legacy.png">
149 </div>
150 <p style="text-align:center">Scheme "Legacy Dark":</p>
151 <div class="images" style="margin: -10px auto 15px auto;">
152 <img class="border" style="max-width: 100%;" src="<?= $CTL ?>/scheme_legacy_dark.png">
153 </div>
154 <p>One important rule: if some color was added to one schema, it should also be added to other schemas. It is also important to check how new added color affects the look of related widgets for these schemas.</p>
155
156 <h2><a href="#rules">Basic color rules and solutions</a></h2>
157
158 <p>In the &quot;MODERN&quot; schema all colors are organized according to the LCH (or HCL) color space which is based on LAB color space. In such color space all colors have perceptual uniformity. That means, that in LCH color space all colors that
159 have the same lighness are perceived as colors that have the same lightness, and all colors that have the same chromaticity are perceived as colors with the same chromaticity.</p>
160
161 <p>Such decision was made for the purpose of making the interface soft and not too motely, and also to make the individual elements not changing the brightness depending on the color tone (as a counterversive part to HSL color space in the
162 &quot;Legacy&quot; schema).</p>
163
164 <p style="text-align:center">It is much easier to understand if we grayscale the pictures for &quot;Modern&quot; and &quot;Legacy&quot; schemas.</p>
165 <div class="grid-2col-man">
166 <div class="thc-descr" style="margin: 0 auto;">
167 <img class="border" src="<?= $CTL ?>/lch_color.png">
168 <img class="border" src="<?= $CTL ?>/lch_gray.png">
169 </div>
170 <div class="thc-descr" style="margin: 0 auto;">
171 <img class="border" src="<?= $CTL ?>/hsl_color.png">
172 <img class="border" src="<?= $CTL ?>/hsl_gray.png">
173 </div>
174 </div>
175
176 <p style="text-align:center">Anyway, it is much easier to add the color to the «Modern» schema just by choosing one of colors from the palette below.</p>
177 <div class="images" style="margin: -10px auto 15px auto;">
178 <img class="border" style="max-width: 100%;" src="<?= $CTL ?>/palette_256.png">
179 </div>
180
181 <p style="text-align:center">In schemas many parameters already have their colors, here are some of them:</p>
182
183 <div class="grid-2col-man">
184 <div class="thc-descr">
185 <pre style="margin-top: 0px; margin-bottom: 0px;">
186 &lt;!-- Knob and meshes colors --&gt;
187 &lt;mono_in value=&quot;#bf6455&quot;/&gt;
188 &lt;mono value=&quot;#d8412a&quot;/&gt;
189 &lt;left_in value=&quot;#bf6455&quot;/&gt;
190 &lt;right_in value=&quot;#717eae&quot;/&gt;
191 &lt;left value=&quot;#d8412a&quot;/&gt;
192 &lt;right value=&quot;#5072f4&quot;/&gt;
193 &lt;mid_in value=&quot;#52888e&quot;/&gt;
194 &lt;side_in value=&quot;#538c50&quot;/&gt;
195 &lt;mid value=&quot;#0090a1&quot;/&gt;
196 &lt;side value=&quot;#009700&quot;/&gt;
197 &lt;velocity value=&quot;#da404a&quot;/&gt;
198 &lt;balance value=&quot;#b07000&quot;/&gt;
199 &lt;fader_balance value=&quot;#b07000&quot;/&gt;
200 &lt;balance_l value=&quot;#b07000&quot;/&gt;
201 &lt;balance_r value=&quot;#868200&quot;/&gt;
202 &lt;envelope value=&quot;#9e60ee&quot;/&gt;
203 &lt;envelope_1 value=&quot;#9e60ee&quot;/&gt;</pre>
204 </div>
205 <div class="thc-descr">
206 <pre style="margin-top: 0px; margin-bottom: 0px;">
207 &lt;envelope_2 value=&quot;#8d76aa&quot;/&gt;
208 &lt;sidechain value=&quot;#c65219&quot;/&gt;
209 &lt;sidechain_1 value=&quot;#c65219&quot;/&gt;
210 &lt;sidechain_2 value=&quot;#b36c49&quot;/&gt;
211 &lt;threshold value=&quot;#c344d3&quot;/&gt;
212 &lt;threshold_1 value=&quot;#c344d3&quot;/&gt;
213 &lt;threshold_2 value=&quot;#c344d3&quot;/&gt;
214 &lt;attack value=&quot;#c2487b&quot;/&gt;
215 &lt;attack_1 value=&quot;#c2487b&quot;/&gt;
216 &lt;attack_2 value=&quot;#c2487b&quot;/&gt;
217 &lt;release value=&quot;#009555&quot;/&gt;
218 &lt;release_1 value=&quot;#009555&quot;/&gt;
219 &lt;release_2 value=&quot;#009555&quot;/&gt;
220 &lt;dry value=&quot;#8c8700&quot;/&gt;
221 &lt;wet value=&quot;#368ccc&quot;/&gt;
222 &lt;lufs value=&quot;#8ab252&quot;/&gt;
223 &lt;bright_lufs value=&quot;#bee784&quot;/&gt;
224 &lt;dark_lufs value=&quot;#557c1e&quot;/&gt;</pre>
225 </div>
226 </div>
227
228 <p>That&rsquo;s why before adding new color to the widget&rsquo;s property it is important to ensure that it is not already defined in the schema.<br />
229 The color in color schema should reflect the meaning of the entity it is operating or the process it is responsible for. In other words, &quot;button_green&quot; is a bad name for the color because even if it is green in current schema, it can
230 surprisingly become of another color in another schema. By the other side, &quot;button_threshold&quot; is a good color name because it tells about the function of the element it is associated with.</p>
231
232 <p>The value of the color can be defined in multiple ways (capital letters mean hexadecimal digits while lower-case letters mean floating-point values often normalized to range 0.0 to 1.0):</p>
233
234 <ul>
235 <li>RGB: #RGB, #RRGGBB, #RRRGGGBBB, rgb(r, g, b); </li>
236 <li>RGBA: #ARGB, #AARRGGBB, #AAARRRGGGBBB, rgba(R, G, B, A); </li>
237 <li>HSL: @HSL, @HHSSLL, @HHHSSSLLL, hsl(H, S, L) </li>
238 <li>HSLA: @AHSL, @AAHHSSLL, @AAAHHHSSSLLL, hsla(H, S, L, A); </li>
239 <li>HCL: hcl(h, c, l); </li>
240 <li>HCLA: hcla(h, c, l, a); </li>
241 <li>LAB: lab(l, a, b); </li>
242 <li>LABA: laba(l, a, b, a); </li>
243 <li>CMYK: cmyk(c, m, y, k); </li>
244 <li>CMYKA: cmyka(c, m, y, k, a). </li>
245 </ul>
246
247 <p>The color is considered fully transparent when the normalized value of the alpha component (a, A) is 1.0, and fully opaque when the normalized value of the alpha component is 0.0. That allows to omit the alpha value for definition of fully opaque
248 colors.</p>
249
250 <p>It is strongly not recommended to explicitly define the value of the color in plugin&rsquo;s UI markup file. Otherwise switching schemas will yield to unexpected results caused by hard-coded colors not blending together with other elements. To
251 prevent such problem, it is strongly recommended to define all colors in schema files.</p>
252
253 <p>If widgets are of the different kind but carry the same meaning, it is important to make them of the same color. It helps to preserve the common style and provide the consistency of the interface.</p>
254
255 <p>Gray tones are used only for inactive (disabled) elements and we don&rsquo;t use it for any plugin&rsquo;s parameter.</p>
256
257 <p style="text-align:center">In the example below the selected filter does not provide band width nor gain controls, that&rsquo;s why corresponding widgets were of the gray color.</p>
258 <div class="images" style="margin: -10px auto 15px auto;">
259 <img class="border" style="max-width: 100%;" src="<?= $CTL ?>/inactive.png">
260 </div>
261
262 <p>The markup language allows to use loops for building multiple blocks of the same pattern.<br />
263 In the example below we can color widgets by setting the base color and altering it&rsquo;s tone by setting different values to the &laquo;hue&raquo; attribute proportionally to the value of the iterator variable:</p>
264
265 <pre>
266 &lt;plugin resizable=&quot;true&quot;&gt;
267 &nbsp;&nbsp;&lt;grid rows=&quot;3&quot; cols=&quot;8&quot; bg.color=&quot;bg_schema&quot; spacing=&quot;4&quot; transpose=&quot;true&quot;&gt;
268 &nbsp;&nbsp;&nbsp;&nbsp;&lt;ui:for id=&quot;i&quot; first=&quot;0&quot; count=&quot;8&quot;&gt;
269 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;label text=&quot;labels.signal.dry&quot;/&gt;
270 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;knob id=&quot;dry&quot; scolor=&quot;cycle&quot; scolor.hue=&quot;${:i * 0.125}&quot;/&gt;
271 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;value id=&quot;dry&quot;/&gt;
272 &nbsp;&nbsp;&nbsp;&nbsp;&lt;/ui:for&gt;
273 &nbsp;&nbsp;&lt;/grid&gt;
274 &lt;/plugin&gt;</pre>
275
276 <p style="text-align:center">This allows to gain the following result:</p>
277 <div class="images" style="margin: -10px auto 15px auto;">
278 <img class="border" style="max-width: 100%;" src="<?= $CTL ?>/cycles.png">
279 </div>
280
281 <p>There are three colors defined for the background in &quot;Modern&quot; schema. Usually, the first color is used by separators and paddings, the second color is used for primary background, the third one is the primary background for widgets in
282 inactive state.</p>
283
284 <p>Instead of highlighting some active element, it is decided in LSP to darken inactive elements. In other words, the block containing widget and all widgets in this block become darken. Scales, buttons, meters and other colored widgets become
285 grayscale (excluding the active ones).</p>
286
287 <div class="images">
288 <img class="border" style="max-width: 100%;" src="<?= $CTL ?>/inactive_2.png">
289 </div>
290
291 <p>In common case it can be performed by manipulating the value of bg.color, and bg.bright properties.</p>
292
293 <p>It is generally accepted to use spacing between blocks of 4 nominal pixels, sometimes additionally separators are applied. The difference between spacings and separators is that separators allow to logically separate widgets in the same block. It
294 is recommended to use separators of the following kind:<em><strong> &lt;vsep pad.h=&quot;2&quot; bg.color=&quot;bg&quot; hreduce=&quot;true&quot;/&gt; </strong></em>or <em><strong>&lt;hsep pad.v=&quot;2&quot; bg.color=&quot;bg&quot;
295 vreduce=&quot;true&quot;/&gt;</strong></em>.</p>
296
297 <p style="text-align:center">Such separators will be visible in other schemas where the color of the background is not altering:</p>
298
299 <pre>
300 &lt;plugin resizable=&quot;true&quot;&gt;
301 &nbsp;&nbsp;&lt;grid rows=&quot;4&quot; cols=&quot;5&quot; bg.color=&quot;bg_schema&quot;&gt;
302 &nbsp;&nbsp;&nbsp;&nbsp;&lt;!-- Row 1 --&gt;
303 &nbsp;&nbsp;&nbsp;&nbsp;&lt;label text=&quot;labels.signal.dry&quot; pad.v=&quot;4&quot;/&gt;
304 &nbsp;&nbsp;&nbsp;&nbsp;&lt;cell rows=&quot;4&quot;&gt;
305 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;vsep pad.h=&quot;2&quot; bg.color=&quot;bg&quot; hreduce=&quot;true&quot;/&gt;
306 &nbsp;&nbsp;&nbsp;&nbsp;&lt;/cell&gt;
307 &nbsp;&nbsp;&nbsp;&nbsp;&lt;label text=&quot;labels.signal.wet&quot; pad.v=&quot;4&quot;/&gt;
308 &nbsp;&nbsp;&nbsp;&nbsp;&lt;cell rows=&quot;4&quot;&gt;
309 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;vsep pad.h=&quot;2&quot; bg.color=&quot;bg&quot; hreduce=&quot;true&quot;/&gt;
310 &nbsp;&nbsp;&nbsp;&nbsp;&lt;/cell&gt;
311 &nbsp;&nbsp;&nbsp;&nbsp;&lt;label text=&quot;labels.output&quot; pad.v=&quot;4&quot;/&gt;
312 &nbsp;&nbsp;&nbsp;&nbsp;&lt;!-- Row 2 --&gt;
313 &nbsp;&nbsp;&nbsp;&nbsp;&lt;hsep pad.v=&quot;2&quot; bg.color=&quot;bg&quot; vreduce=&quot;true&quot;/&gt;
314 &nbsp;&nbsp;&nbsp;&nbsp;&lt;hsep pad.v=&quot;2&quot; bg.color=&quot;bg&quot; vreduce=&quot;true&quot;/&gt;
315 &nbsp;&nbsp;&nbsp;&nbsp;&lt;hsep pad.v=&quot;2&quot; bg.color=&quot;bg&quot; vreduce=&quot;true&quot;/&gt;
316 &nbsp;&nbsp;&nbsp;&nbsp;&lt;!-- Row 3 --&gt;
317 &nbsp;&nbsp;&nbsp;&nbsp;&lt;knob id=&quot;dry&quot; scale.color=&quot;dry&quot; pad.v=&quot;4&quot;/&gt;
318 &nbsp;&nbsp;&nbsp;&nbsp;&lt;knob id=&quot;wet&quot; scolor=&quot;wet&quot; pad.v=&quot;4&quot;/&gt;
319 &nbsp;&nbsp;&nbsp;&nbsp;&lt;knob id=&quot;g_out&quot; pad.v=&quot;4&quot;/&gt;
320 &nbsp;&nbsp;&nbsp;&nbsp;&lt;!-- Row 4 --&gt;
321 &nbsp;&nbsp;&nbsp;&nbsp;&lt;value id=&quot;dry&quot; pad.b=&quot;4&quot;/&gt;
322 &nbsp;&nbsp;&nbsp;&nbsp;&lt;value id=&quot;wet&quot; pad.b=&quot;4&quot;/&gt;
323 &nbsp;&nbsp;&nbsp;&nbsp;&lt;value id=&quot;g_out&quot; pad.b=&quot;4&quot;/&gt;
324 &nbsp;&nbsp;&lt;/grid&gt;
325 &lt;/plugin&gt;</pre>
326
327 <div class="grid-2col-man">
328 <div class="thc-descr" style="margin: 0 auto;">
329 <img class="border" src="<?= $CTL ?>/separator_modern.png">
330 </div>
331 <div class="thc-descr" style="margin: 0 auto;">
332 <img class="border" src="<?= $CTL ?>/separator_legacy.png">
333 </div>
334 </div>
335
336 <p>Internal paddings for widgets of the same block have 6 nominal pixels in the horizontal direction and 4 nominal pixels in the vertical direction.</p>
337
338 <p>While designing the user interface, it is generally accepted to always show all possible elements like knobs, combo boxes, buttons, etc. If under certain conditions widget is useless, we don&rsquo;t hide it from the UI but make inactive (gray
339 color and dark background if necessary). This allows to make the UI look more stable, no window resize nor content flickering happens.</p>
340
341 <p>It is strongly recommended to verify the maximum and minimum values of the <strong><em>&lt;value&gt;</em></strong> widget. For this purpose just put the corresponding control element into the minimum and maximum positions. If the values are
342 flickering and force to flicker the neighbor widgets, it is required to explicitly specify the minimum widget width that allows to fully fit the minimum and maximum value text.</p>
343
344 <pre>
345 &lt;plugin resizable=&quot;true&quot;&gt;
346 &nbsp;&nbsp;&lt;grid rows=&quot;4&quot; cols=&quot;5&quot; bg.color=&quot;bg_schema&quot;&gt;
347 &nbsp;&nbsp;&nbsp;&nbsp;&lt;!-- Row 1 --&gt;
348 &nbsp;&nbsp;&nbsp;&nbsp;&lt;label text=&quot;labels.signal.dry&quot; pad.v=&quot;4&quot;/&gt;
349 &nbsp;&nbsp;&nbsp;&nbsp;&lt;cell rows=&quot;4&quot;&gt;
350 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;vsep pad.h=&quot;2&quot; bg.color=&quot;bg&quot; hreduce=&quot;true&quot;/&gt;
351 &nbsp;&nbsp;&nbsp;&nbsp;&lt;/cell&gt;
352 &nbsp;&nbsp;&nbsp;&nbsp;&lt;label text=&quot;labels.signal.wet&quot; expand=&quot;true&quot; pad.v=&quot;4&quot;/&gt;
353 &nbsp;&nbsp;&nbsp;&nbsp;&lt;cell rows=&quot;4&quot;&gt;
354 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;vsep pad.h=&quot;2&quot; bg.color=&quot;bg&quot; hreduce=&quot;true&quot;/&gt;
355 &nbsp;&nbsp;&nbsp;&nbsp;&lt;/cell&gt;
356 &nbsp;&nbsp;&nbsp;&nbsp;&lt;label text=&quot;labels.output&quot; pad.v=&quot;4&quot;/&gt;
357 &nbsp;&nbsp;&nbsp;&nbsp;&lt;!-- Row 2 --&gt;
358 &nbsp;&nbsp;&nbsp;&nbsp;&lt;hsep pad.v=&quot;2&quot; bg.color=&quot;bg&quot; vreduce=&quot;true&quot;/&gt;
359 &nbsp;&nbsp;&nbsp;&nbsp;&lt;hsep pad.v=&quot;2&quot; bg.color=&quot;bg&quot; vreduce=&quot;true&quot;/&gt;
360 &nbsp;&nbsp;&nbsp;&nbsp;&lt;hsep pad.v=&quot;2&quot; bg.color=&quot;bg&quot; vreduce=&quot;true&quot;/&gt;
361 &nbsp;&nbsp;&nbsp;&nbsp;&lt;!-- Row 3 --&gt;
362 &nbsp;&nbsp;&nbsp;&nbsp;&lt;knob id=&quot;dry&quot; scale.color=&quot;dry&quot; pad.v=&quot;4&quot; pad.h=&quot;6&quot;/&gt;
363 &nbsp;&nbsp;&nbsp;&nbsp;&lt;knob id=&quot;wet&quot; scale.color=&quot;wet&quot; pad.v=&quot;4&quot;/&gt;
364 &nbsp;&nbsp;&nbsp;&nbsp;&lt;knob id=&quot;g_out&quot; pad.v=&quot;4&quot; pad.h=&quot;6&quot;/&gt;
365 &nbsp;&nbsp;&nbsp;&nbsp;&lt;!-- Row 4 --&gt;
366 &nbsp;&nbsp;&nbsp;&nbsp;&lt;value id=&quot;dry&quot; pad.b=&quot;4&quot; same.line=&quot;true&quot;/&gt;
367 &nbsp;&nbsp;&nbsp;&nbsp;&lt;value id=&quot;wet&quot; pad.b=&quot;4&quot; same.line=&quot;true&quot;/&gt;
368 &nbsp;&nbsp;&nbsp;&nbsp;&lt;value id=&quot;g_out&quot; pad.b=&quot;4&quot; same.line=&quot;true&quot;/&gt;
369 &nbsp;&nbsp;&lt;/grid&gt;
370 &lt;/plugin&gt;</pre>
371 <div class="images">
372 <img class="border" style="max-width: 100%;" src="<?= $CTL ?>/shake.gif">
373 </div>
374
375 <p>On the picture above we observe the flickering of the UI when adjusting the value of the &quot;Dry&quot; knob. To solve this, we alternate the tag <strong><em>&lt;value id=&quot;dry&quot; pad.b=&quot;4&quot;
376 same.line=&quot;true&quot;/&gt;</em></strong> and append additional property <strong><em>width.min=&quot;48&quot;</em></strong>. Finally the tag now looks like this: <strong><em>&lt;value id=&quot;dry&quot; pad.b=&quot;4&quot;
377 same.line=&quot;true&quot; width.min=&quot;48&quot;/&gt;</em></strong>. The result is on the picture below:</p>
378
379
380 <div class="images">
381 <img class="border" style="max-width: 100%;" src="<?= $CTL ?>/no_shake.gif">
382 </div>
383
384 <p>The interface allows to change it&rsquo;s size on the fly: change the size of the window and scale the size of the nominal pixel. So it is important to verify how the plugin will look like when the window becomes expanded to the full screen. It is
385 important to ensure that the only designed for expanding elements will take the free space while other elements will keep their sizes.</p>
386
387
388 <p style="text-align:center">Normal size:</p>
389 <div class="images" style="margin: -10px auto 15px auto;">
390 <img class="border" style="max-width: 100%;" src="<?= $CTL ?>/gott.png">
391 </div>
392
393 <p style="text-align:center">Full screen size:</p>
394 <div class="images" style="margin: -10px auto 15px auto;">
395 <img class="border" style="max-width: 100%;" src="<?= $CTL ?>/gott_full_screen.png">
396 </div>
397
398 <p>The properties expand, vexpand, hexpand are responsible for expanding the widgets. If the only one element in the grid will contain such property, then only this widget will take the maximum possible space. In the case when there are more than one
399 expanding widgets, then they will share the space proportionally to their sizes. Usually these properties are applied to graphs or widgets that provide some visual information.</p>
400
401 <h2><a href="#components">Sections and components</a></h2>
402 <p>The interface is split into three parts: top panel, the body and the bottom panel.</p>
403
404 <p>&nbsp;</p>
405
406 <h3>Top panel</h3>
407
408 <p>At the left the logo is located. At the top right corner the name of the plugin is placed. At the right bottom corner global controls are placed which are common for all plugins.</p>
409
410 <div class="images">
411 <img class="border" style="max-width: 100%;" src="<?= $CTL ?>/top.png">
412 </div>
413
414 <h3>Body</h3>
415
416 <p>In the plugin&rsquo;s body are located wigets responsible for the plugin&rsquo;s configuration and for display of actual plugin&rsquo;s state.</p>
417
418 <div class="images">
419 <img class="border" style="max-width: 100%;" src="<?= $CTL ?>/middle.png">
420 </div>
421
422 <p>In the body of the plugin there can be such elements as:</p>
423
424 <p>&nbsp;</p>
425
426 <h4>Graph</h4>
427
428 <p>The graph widget can contain necessary curves displaying, for example, the spectrum of the signal, or control elements like dots and markers.</p>
429
430 <p>It is generally accepted to add the title to the graph. For example, the &laquo;Spectrum graph&raquo; below:</p>
431
432 <div class="images">
433 <img class="border" style="max-width: 100%;" src="<?= $CTL ?>/graph.png">
434 </div>
435
436 <h4>Group</h4>
437
438 <p>In this widgets the widgets of the same meaning or functionality are usually placed. For example, the knobs that control the levels of input and output signals. The group can contain some heading or can not contain it.</p>
439
440 <div class="images">
441 <img class="border" style="max-width: 100%;" src="<?= $CTL ?>/group.png">
442 </div>
443
444 <p>There are also widgets of the same to<strong><em> &lt;group&gt; </em></strong>meaning: <strong><em>&lt;tabs&gt; and &lt;cgroup&gt;</em></strong>. They are designed for paging purpose and paginized access to the huge amount of control elements such
445 as filter parameters in the equalizer or different sample manipulations in sampler.</p>
446
447 <div class="images">
448 <img class="border" style="max-width: 100%;" src="<?= $CTL ?>/tabs.png">
449 </div>
450
451 <div class="images">
452 <img class="border" style="max-width: 100%;" src="<?= $CTL ?>/cgroup.png">
453 </div>
454
455 <p>It is also commonly accepted to group together widgets of the similar meaning or related to the same actions. They can be not organized into groups but split with separators as it done with LUFS control in the clipper plugin. The
456 <strong><em>&lt;ledmeter&gt;, &lt;button&gt; </em></strong>and<strong><em> &lt;knob&gt;</em></strong> are placed in the same block.
457 </p>
458
459 <div class="images">
460 <img class="border" style="max-width: 100%;" src="<?= $CTL ?>/lufs_group.png">
461 </div>
462
463 <h4>Label</h4>
464 <p>This widget is used to deliver some text information. It is strongly denied to hard-code the text of the label inside of the markup file if it can contain non-numeric value. All values and parameters should be added to localization files in JSON
465 format. Meanwhile the associated localization key should be of the similar sense the text of the label is holding. It is required to add localization keys and localization values at least into two sub-trees: default and us. But if you&rsquo;re the
466 native speaker of other languages present in the localization tree, it is a good tone to add translations for your native language, too.</p>
467
468 <h4>Value</h4>
469 <p>This widget is also designed to deliver some text information. The main difference to the label is that it displays the actual value of some plugin&rsquo;s parameter.</p>
470
471 <h4>Buttons</h4>
472 <p>Buttons are widgets that allow to turn on, turn off, switch the parameter or act as a trigger. It is allowed to place some text inside of the button related to some parameter or action the button is dealing with. The rules of adding text are the
473 same to the rules of adding text to the label. There are some predefined styles in the schemas for buttons. For example, &quot;Button_stretch_8&quot;. The &quot;stretch&quot; word means that this button is related to the stretching functions and is
474 associated with colors that are coding the stretching function. The number &quot;8&quot; informs about the size of the text inside of the button.</p>
475
476 <h4>Meters</h4>
477 <p>This type of widgets usually displays the loudness level or the level of impact. It is accepted to supply some label near the meter widget for better understanding of the entity or process it is associated with. As an exception, the clarifying
478 label can be omitted when the designation of the widget is obvious even without any captions. For example, when the meter is placed in the same group with some single parameter.</p>
479
480 <h4>Fader</h4>
481 <p>This widget can be horizontal or vertical. The main sense of this widget is to change plugin&rsquo;s parameters. It is very often used for control over zoom on graph widgets.</p>
482
483 <h4>Knobs</h4>
484 <p>Same to the fader, knobs are designed for control over some plugin&rsquo;s parameter. The same way to the buttons knobs also have predefined styles in schemas. Knob allows to change many parameters like it&rsquo;s overall size or the width of the
485 scale but in many cases with the purpose of the color coding the color of the knob&rsquo;s scale is altered.</p>
486
487 <h3>Bottom panel</h3>
488
489 <p>The bottom panel contains elements which are common for all plugins. The buttons for window sizing, text sizing, UI scaling. This panel is accepted for placing only of control elements shared by all plugins and rarely used.</p>
490
491 <div class="images">
492 <img class="border" style="max-width: 100%;" src="<?= $CTL ?>/bottom.png">
493 </div>
494
495 <p>It should be noted that the overall plugin design and concept of the concrete schema should be taken into attention. The newly created widget should follow the common scheme, for example not use corner rounding for the schema where the corner
496 rounding is not used.</p>
497
498 <p>It is also should be noted that the LSP toolkit contains much more widgets but their detailed description will take much more time. LSP Project&rsquo;s team will prefer to spend time for introduction new functionality. But initiative and
499 contribution to the project are affordable and welcome.</p>
500
501 <p>To understand the complete set of attributes provided by the widget, it is a good reason to look inside the code of the widget placed in the lsp-tk-lib library and find it&rsquo;s style definition.</p>
502
503 <p style="text-align:center">For example, in the Knob.cpp file contains the following style definition:</p>
504 <pre>LSP_TK_STYLE_IMPL_BEGIN(Knob, Widget)
505 // Bind
506 sColor.bind("color", this);
507 sScaleColor.bind("scale.color", this);
508 sBalanceColor.bind("balance.color", this);
509 sHoleColor.bind("hole.color", this);
510 sTipColor.bind("tip.color", this);
511 sBalanceTipColor.bind("balance.tip.color", this);
512 sMeterColor.bind("meter.color", this);
513 sSizeRange.bind("size.range", this);
514 sScale.bind("scale.size", this);
515 sValue.bind("value", this);
516 sStep.bind("step", this);
517 sBalance.bind("value.balance", this);
518 sMeterMin.bind("meter.min", this);
519 sMeterMax.bind("meter.max", this);
520 sCycling.bind("value.cycling", this);
521 sScaleMarks.bind("scale.marks", this);
522 sBalanceColorCustom.bind("balance.color.custom", this);
523 sFlat.bind("flat", this);
524 sScaleActive.bind("scale.active", this);
525 sMeterActive.bind("meter.active", this);
526 sEditable.bind("editable", this);
527 sHoleSize.bind("hole.size", this);
528 sGapSize.bind("gap.size", this);
529 sScaleBrightness.bind("scale.brightness", this);
530 sBalanceTipSize.bind("balance.tip.size", this);
531 sBalanceTipColorCustom.bind("balance.tip.color.custom", this);
532 sInvertMouseVScroll.bind("mouse.vscroll.invert", this);
533 // Configure
534 sColor.set("#cccccc");
535 sScaleColor.set("#00cc00");
536 sBalanceColor.set("#0000cc");
537 sHoleColor.set("#000000");
538 sMeterColor.set("#88ff0000");
539 sTipColor.set("#000000");
540 sBalanceTipColor.set("#0000ff");
541 sSizeRange.set(8, -1);
542 sScale.set(4);
543 sValue.set_all(0.5f, 0.0f, 1.0f);
544 sStep.set(0.01f);
545 sBalance.set(0.5f);
546 sMeterMin.set(0.0f);
547 sMeterMax.set(0.0f);
548 sCycling.set(false);
549 sScaleMarks.set(true);
550 sBalanceColorCustom.set(false);
551 sFlat.set(false);
552 sScaleActive.set(true);
553 sMeterActive.set(false);
554 sEditable.set(true);
555 sHoleSize.set(1);
556 sGapSize.set(1);
557 sScaleBrightness.set(0.75f);
558 sBalanceTipSize.set(0);
559 sBalanceTipColorCustom.set(false);
560 sInvertMouseVScroll.set(false);
561 LSP_TK_STYLE_IMPL_END
562 LSP_TK_BUILTIN_STYLE(Knob, "Knob", "root");
563 </pre>
564
565 <p>Here we see that the LSP_TK_STYLE_IMPL_BEGIN macro defines new style class Knob which is derived from Widget style class (and contains it&rsquo;s own properties). Next, we seee the block of code that performs bindinf of properties to the name of
566 style attributes in the XML schema file. In other words, the attribute &lt;color&gt; in the XML file will be associated with the sColor property in the source code when parsing the schema file.<br />
567 A bit below one another block of code is placed &mdash; the initialization block which configures the default values for properties of this style.<br />
568 The style definition is terminated by the LSP_TK_STYLE_IMPL_END macro.<br />
569 But it is important not only to declare the style class but also to add a factory which will register this style class in the widget library. The macro LSP_TK_BUILTIN_STYLE is responsible for it. It also defines the name of the style in the XML
570 schema file (&quot;Knob&quot;) and the name of the parent style the style is derived from (&quot;root&quot;).</p>