WSL/SLF GitLab Repository

help_dev.xml 56.8 KB
Newer Older
1
2
3
4
5
6
<!--
/*****************************************************************************/
/*  Copyright 2019 WSL Institute for Snow and Avalanche Research  SLF-DAVOS  */
/*****************************************************************************/
/* This file is part of INIshell.
   INIshell is free software: you can redistribute it and/or modify
7
   it under the terms of the GNU General Public License as published by
8
9
10
11
12
13
   the Free Software Foundation, either version 3 of the License, or
   (at your option) any later version.

   INIshell is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14
   GNU General Public License for more details.
15

16
17
   You should have received a copy of the GNU General Public License
   along with INIshell.  If not, see <http://www.gnu.org/licenses/>.
18
19
20
21
*/
-->

<!--
22
23
This is the developer's guide which is meant for people who want to use INIshell to control
their own simulation software. It showcases all panels and lists their options.
24
25
26
-->

<inishell_config>
27

28
	<!-- INTRODUCTION -->
29

30
31
	<parameter type="label" label="&lt;h3&gt;Principles of &lt;i&gt;INIshell&lt;/i&gt;&lt;/h3&gt;" color="sl_blue">
		<section name="Introduction" color="sl_blue"/>
32
	</parameter>
33
34
35
36
37
38
39
40
	<parameter type="helptext" wrap="true">
		<section name="Introduction"/>
		<help>&lt;i&gt;INIshell&lt;/i&gt; aims to facilitate controlling software with text-based settings which is normally run in a terminal. With fast-changing simulation software and fast-changing requirements it needs to be flexible enough to quickly adapt to changes in the controlled program's available settings and syntax.</help>
	</parameter>
	<parameter type="helptext" wrap="true">
		<section name="Introduction"/>
		<help>This is realized by reading an application's available settings at runtime from an XML file. This XML file describes to &lt;i&gt;INIshell&lt;/i&gt; which parameters the controlled model knows, and of what type they are. &lt;i&gt;INIshell&lt;/i&gt; takes this information and builds a panel the user can interact with to change the specific key. This way, if the controlled software changes, these changes only need to be reflected in the describing XML file, but not in &lt;i&gt;INIshell&lt;/i&gt;'s source code. &lt;br&gt;</help>
	</parameter>
41
	<frame caption="Introduction to using INIshell as developer" color="sl_blue">
42
43
44
		<section name="Introduction"/>
		<parameter type="helptext" wrap="true">
			<help>An &lt;i&gt;INIshell&lt;/i&gt; file needs an appropriate header to be identified as a file that contains an application's configuration:&lt;br&gt;</help>
45
		</parameter>
46
47
48
49
50
51
52
53
54
55
		<parameter type="helptext" wrap="true">
			<help>&lt;code&gt;&amp;lt;inishell_config application=&quot;SNOWPACK&quot;&amp;gt;&lt;br&gt;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;...&lt;br&gt;&amp;lt;/inishell_config&amp;gt;&lt;/code&gt;&lt;br&gt;</help>
		</parameter>
		<parameter type="helptext" wrap="true">
			<help>Or, to indicate that this is a simulation's configuration:&lt;br&gt;</help>
		</parameter>
		<parameter type="helptext" wrap="true">
			<help>&lt;code&gt;&amp;lt;inishell_config simulation=&quot;Weißfluhjoch&quot;&amp;gt;&lt;br&gt;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;...&lt;br&gt;&amp;lt;/inishell_config&amp;gt;&lt;/code&gt;&lt;br&gt;</help>
		</parameter>
		<parameter type="helptext" wrap="true">
56
			<help>There is no logical difference between applications and simulations as far as &lt;i&gt;INIshell&lt;/i&gt; is concerned; so the only thing the different identifier does is to put it in the respective &lt;font color=&quot;#268bd2&quot;&gt;Applications&lt;/font&gt; or &lt;font color=&quot;#268bd2&quot;&gt;Simulations&lt;/font&gt; workflow tab. Thus, the principles discussed here apply to both setups.</help>
57
58
59
60
61
62
63
64
65
66
67
		</parameter>
		<parameter type="helptext" wrap="true">
			<help>Within these tags reside the descriptions of the elements that &lt;i&gt;INIshell&lt;/i&gt; should display. For each text panel, number panel, help text, ..., there is an XML node for it concisely telling &lt;i&gt;INIshell&lt;/i&gt; the formatting options. For example, a simple text panel for modifying the INI key &lt;code&gt;TEXT_FIELD&lt;/code&gt; may look like this:&lt;br&gt;</help>
		</parameter>
		<parameter type="helptext" wrap="true">
			<help>&lt;code&gt;&amp;lt;parameter key=&quot;TEXT_FIELD&quot; type=&quot;text&quot;/&amp;gt;&lt;/code&gt;&lt;br&gt;</help>
		</parameter>
		<parameter type="helptext" wrap="true">
			<help>More complicated panels may have child panels; for example, each item of a dropdown element can display different additional panels. This can be nested indefinitely allowing for quite complex settings. See the different tabs of this help file for which options the panels support.</help>
		</parameter>
		<parameter type="helptext" wrap="true">
68
			<help>The same is true for the workflow panel (the left side of &lt;i&gt;INIshell&lt;/i&gt;). Only a few tabs are fixed, the rest is also read from XML, albeit with different panels available. See the &lt;font color=&quot;#268bd2&quot;&gt;Workflow&lt;/font&gt; section of this help.</help>
69
		</parameter>
70
	</frame>
71
	<frame caption="First example" color="sl_blue">
72
73
74
75
76
77
78
79
		<section name="Introduction"/>
		<parameter type="helptext" wrap="true">
			<help>Put the panel description in the main XML and you have a first valid inishell config file:&lt;br&gt;</help>
		</parameter>
		<parameter type="helptext" wrap="true">
			<help>&lt;code&gt;&amp;lt;inishell_config application=&quot;my_application&quot;&amp;gt;&lt;br&gt;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;lt;parameter key=&quot;TEXT_FIELD&quot; type=&quot;text&quot;/&amp;gt;&lt;br&gt;&amp;lt;/inishell_config&amp;gt;&lt;/code&gt;&lt;br&gt;</help>
		</parameter>
	</frame>
80

81
	<!-- WORKFLOW -->
82

83
	<parameter type="label" label="&lt;h3&gt;Workflow panel&lt;/h3&gt;">
84
		<section name="Workflow" color="sl_blue"/>
85
	</parameter>
86
	<section name="Workflow" color="sl_blue"> <!-- another way to give a section name for all child nodes -->
87
88
89
		<parameter type="helptext" wrap="true">
			<help>See the user's guide under section &lt;font color=&quot;#4e81d4&quot;&gt;Configuring simulations&lt;/font&gt; for an introduction about the workflow panel. XML nodes within the parent &lt;code&gt;&amp;lt;workflow&amp;gt;&lt;/code&gt; node (must have exactly this name) are parsed with different available panels than for the main panel.&lt;br&gt;</help>
		</parameter>
90
		<frame caption="Structure" color="sl_blue">
91
92
93
94
			<parameter type="helptext" wrap="true">
				<help>Somewhere in the XML document and its includes there must be one or more &lt;b&gt;&amp;lt;workflow&amp;gt;&lt;/b&gt; sections to add workflow panels. In there, you separate the workflow tabs by &lt;b&gt;&amp;lt;section&amp;gt;&lt;/b&gt; nodes, in which you can build &lt;b&gt;&amp;lt;element&amp;gt;&lt;/b&gt; nodes. Note that in order to remember that these sections have nothing to do with our INI sections, they have a &lt;code&gt;caption&lt;/code&gt; instead of a &lt;code&gt;name&lt;/code&gt;. The code in the next frame is a fully defined workflow tab.</help>
			</parameter>
		</frame>
95
		<frame caption="Buttons" color="sl_blue">
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
			<parameter type="helptext" wrap="true">
				<help>A &lt;b&gt;button&lt;/b&gt; can have one or more system commands that it will run, specified in separate &lt;code&gt;&amp;lt;command&amp;gt;&lt;/code&gt; nodes:&lt;br&gt;</help>
			</parameter>
			<parameter type="helptext" wrap="true">
				<help>&lt;code&gt;&amp;lt;workflow&amp;gt;&lt;br&gt;
					&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;lt;section caption=&quot;My Workflow Panel&quot;&amp;gt;&lt;br&gt;
					&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;lt;element caption=&quot;Run experiment&quot; type=&quot;button&quot;&amp;gt;&lt;br&gt;
					&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;lt;command&amp;gt;snowpack -c %ini_wfj -e &lt;b&gt;%end_date_wfj&lt;/b&gt;&amp;lt;/command&amp;gt;&lt;br&gt;
					&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;lt;command&amp;gt;setpath(&lt;b&gt;%meteo_out&lt;/b&gt;, simulations/example_simulation/output)&amp;lt;/command&amp;gt;&lt;br&gt;
					&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;lt;/element&amp;gt;&lt;br&gt;
					&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;lt;/section&amp;gt;&lt;br&gt;
					&amp;lt;/workflow&amp;gt;/code&gt;&lt;br&gt;</help>
			</parameter>
			<parameter type="helptext" wrap="true">
				<help>A button can perform the following operations if put in a &lt;code&gt;command&lt;/code&gt;:&lt;ul&gt;
					&lt;li&gt;Run a system command like shown above&lt;/li&gt;
					&lt;li&gt;Open an URL in the browser with the following syntax: &lt;code&gt;openurl(https://www.slf.ch)&lt;/code&gt;&lt;/li&gt;
113
					&lt;li&gt;Click another button (e. g. for a &quot;Run all&quot; button) like so: &lt;code&gt;button(%button_id)&lt;/code&gt;&lt;/li&gt;
114
					&lt;li&gt;Navigate a &lt;code&gt;Path&lt;/code&gt; element (cf. the &quot;Path view&quot; segment) via &lt;code&gt;setpath(%element_id, path/to/simulation)&lt;/code&gt;&lt;/li&gt;
115
116
117
118
					&lt;li&gt;A button turns into a &quot;Stop process&quot; button when running a system command.&lt;/li&gt;
					&lt;/ul&gt;</help>
			</parameter>
		</frame>
119
		<frame caption="Text fields" color="sl_blue">
120
121
			<parameter type="label" label="Referencing elements:" underline="true"/>
			<parameter type="helptext" wrap="true">
122
				<help>Elements can be given a key to reference them. In the example above, we have referenced two other elements with the syntax &lt;code&gt;%id_of_element&lt;/code&gt;. The corresponding element to &lt;code&gt;ini_wfj&lt;/code&gt; could look like the following. See the provided Weißfluhjoch &lt;code&gt;workflow_wfj.xml&lt;/code&gt; for the full syntax.&lt;br&gt;</help>
123
124
125
126
127
			</parameter>
			<parameter type="helptext" wrap="true">
				<help>&lt;code&gt;&amp;lt;element id=&quot;&lt;b&gt;ini_wfj&lt;/b&gt;&quot; type=&quot;text&quot; default=&quot;simulations/example_simulation/io_res5exp.ini&quot;/&amp;gt;&lt;/code&gt;</help>
			</parameter>
		</frame>
128
		<frame caption="Default arguments" color="sl_blue">
129
130
131
132
			<parameter type="helptext" wrap="true">
				<help>As you can see above, you can supply default arguments for the elements you build.</help>
			</parameter>
		</frame>
133
		<frame caption="Substitutions" color="sl_blue">
134
135
136
137
138
139
140
141
142
143
144
			<parameter type="helptext" wrap="true">
				<help>The following dynamic substitutions are available:</help>
			</parameter>
			<parameter type="helptext" wrap="true">
				<help>&lt;ul&gt;
					&lt;li&gt;&lt;code&gt;%element_id&lt;/code&gt; to reference another workflow panel element&lt;/li&gt;
					&lt;li&gt;&lt;code&gt;${inifile}&lt;/code&gt; for the INI file that is currently opened&lt;/li&gt;
					&lt;li&gt;&lt;code&gt;${key:my_ini_key}&lt;/code&gt; to reference currently known INI values&lt;/li&gt;
					&lt;/ul&gt;</help>
			</parameter>
		</frame>
145
		<frame caption="Date/time pickers" color="sl_blue">
146
147
148
149
150
151
152
			<parameter type="helptext" wrap="true">
				<help>A date/time picker is avaiable via the &lt;code&gt;datetime&lt;/code&gt; identifier:</help>
			</parameter>
			<parameter type="helptext" wrap="true">
				<help>&amp;lt;element id=&quot;&lt;b&gt;end_date_wfj&lt;/b&gt;&quot; type=&quot;datetime&quot; default=&quot;1986-12-25T18:16&quot;/&amp;gt;</help>
			</parameter>
		</frame>
153
		<frame caption="Path views" color="sl_blue">
154
155
156
157
158
159
160
161
162
163
164
165
166
			<parameter type="helptext" wrap="true">
				<help>A specific folder can be set for which the contents are displayed in a folder view element called by the &lt;code&gt;path&lt;/code&gt; tag. You can either set a folder in the &lt;code&gt;path=&quot;...&quot;&lt;/code&gt; attribute, or the path can be set at runtime with a button (or you can leave it empty).&lt;br&gt;</help>
			</parameter>
			<parameter type="helptext" wrap="true">
				<help>&lt;code&gt;&amp;lt;element type=&quot;path&quot; id=&quot;meteo_out&quot;/&amp;gt;&lt;/code&gt;&lt;br&gt;</help>
			</parameter>
			<parameter type="helptext" wrap="true">
				<help>To change the directory to point to with a button click, use a button command like this:&lt;br&gt;</help>
			</parameter>
			<parameter type="helptext" wrap="true">
				<help>&lt;code&gt;&amp;lt;command&amp;gt;setpath(&lt;b&gt;%meteo_out&lt;/b&gt;, simulations/example_simulation/output)&amp;lt;/command&amp;gt;&lt;/code&gt;</help>
			</parameter>
		</frame>
167
		<frame caption="Checkboxes" color="sl_blue">
168
169
170
171
172
173
			<parameter type="helptext" wrap="true">
				<help>Show checkbox to get a boolean value from. Example:</help>
			</parameter>
			<parameter type="helptext" wrap="true">
				<help>&amp;lt;element id="workflow_checkbox" type="checkbox" caption="A checkbox can return &lt;code&gt;TRUE&lt;/code&gt; or &lt;code&gt;FALSE&lt;/code&gt;."/&amp;gt;&lt;br&gt;
					&amp;lt;element caption="Test checkbox" type="button"&amp;gt;&lt;br&gt;
Michael Reisecker's avatar
Michael Reisecker committed
174
					&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;lt;command&amp;gt;echo Checkbox state: %workflow_checkbox&amp;lt;/command&amp;gt;&lt;br&gt;
175
176
177
					&amp;lt;/element&amp;gt;</help>
			</parameter>
		</frame>
178
		<frame caption="Labels" color="sl_blue">
179
180
181
182
183
184
185
			<parameter type="helptext" wrap="true">
				<help>Info labels can be shown via a &lt;code&gt;label&lt;/code&gt; node and can be colored / styled with HTML syntax:&lt;br&gt;</help>
			</parameter>
			<parameter type="helptext" wrap="true">
				<help>&lt;code&gt;&amp;lt;element type=&quot;label&quot; caption=&quot;Weißfluhjoch 1996&quot;/&amp;gt;&lt;/code&gt;</help>
			</parameter>
		</frame>
186
		<frame caption="Working directory" color="sl_blue">
187
188
189
190
			<parameter type="helptext" wrap="true">
				<help>If the workflow incorporates actions such as running programs, a dropdown menu to set the current working directory will be generated automatically.</help>
			</parameter>
		</frame>
191
	</section>
192

193
	<!-- SECTIONS -->
194

195
196
	<parameter type="label" label="&lt;h3&gt;Sections&lt;/h3&gt;" color="sl_blue">
		<section name="Sections" color="sl_blue"/>
197
198
199
200
201
	</parameter>
	<parameter type="helptext" wrap="true">
		<section name="Sections"/>
		<help>Sections are sections in the INI file and displayed in the main panel's tab bar. Each parameter must have a section; if none is given, it will be deafulted to &lt;code&gt;[General]&lt;/code&gt;.&lt;br&gt;</help>
	</parameter>
202
	<frame caption="Ways of specifying a section for the panel" color="sl_blue">
203
204
205
206
207
208
		<section name="Sections"/>
		<parameter type="helptext" wrap="true">
			<help>&lt;ul&gt;
				&lt;li&gt;Each frame/parameter can have a &lt;code&gt;section&lt;/code&gt; tag as child node.&lt;/li&gt;
				&lt;li&gt;Parameters that don't have a parent section will be defaulted to the default section at the top level.&lt;/li&gt;
				&lt;li&gt;Children can not switch parents, so the parent's section counts.&lt;/li&gt;
209
210
				&lt;li&gt;But you can supply as many &lt;code&gt;parent&lt;/code&gt; sections as you like. Then each child can tell in a list of their own &lt;code&gt;section&lt;/code&gt; tags if it should be built for this specific section or not.&lt;/li&gt;
				&lt;li&gt;This is also possible for some child panel's items. For example, an &lt;code&gt;Alternative&lt;/code&gt; panel (a dropdown list) can be set to contribute both to the &lt;code&gt;[INPUT]&lt;/code&gt; and the &lt;code&gt;[OUTPUT]&lt;/code&gt; section. The individual items can be set to appear in either or both of the sections by giving &lt;code&gt;section&lt;/code&gt; child nodes.&lt;/li&gt;
211
212
213
214
215
216
217
218
				&lt;li&gt;You may alternatively supply the &lt;code&gt;section&lt;/code&gt; attribute to the panel's node itself.&lt;/li&gt;
				&lt;li&gt;And lastly, you can construct a &lt;code&gt;&amp;lt;section&amp;gt;&lt;/code&gt; parent node in which you put children.&lt;/li&gt;
				&lt;li&gt;The section format (color, capitalization) is taken from the first occurrence of the &lt;code&gt;section&lt;/code&gt; tag.&lt;/li&gt;
				&lt;li&gt;(Note that currently coloring is not supported uniformly, so if it doesn't work try a different way of giving the section.)&lt;/li&gt;
				&lt;/ul&gt;</help>
		</parameter>
	</frame>
	<parameter type="helptext" wrap="true" section="Sections">
219
		<help>&lt;br&gt;Have a look at this help file's source code (&lt;code&gt;./inishell --dump_help&lt;/code&gt;, cf. command line tools). Up until now we chose the method of supplying a &lt;code&gt;section&lt;/code&gt; child node to tell the parent to go into a certain section. Starting with this frame, we sometimes supply it in the attributes. Later, we will use dedicated &amp;lt;&lt;code&gt;section&lt;/code&gt;&amp;gt; nodes.</help>
220
	</parameter>
221
222
223
224
225
226
	<frame caption="Dynamic sections" color="sl_blue">
		<section name="Sections"/>
		<parameter type="helptext" wrap="true">
			<help>Dedicated &amp;lt;&lt;code&gt;section&lt;/code&gt;&amp;gt; nodes are required to be used for an advanced feature of sections: Like &lt;code&gt;Replicators&lt;/code&gt; they can receive a &lt;code&gt;replicate="true"&lt;/code&gt; property in which case their tab will show a plus button to duplicate the whole section (with a number appended as the new section name).</help>
		</parameter>
	</frame>
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
	<parameter type="helptext" wrap="true" section="Sections">
		<help>The following XML node will construct an Alternative panel that appears in both the &lt;code&gt;[INPUT]&lt;/code&gt; and &lt;code&gt;[OUTPUT]&lt;/code&gt; sections. But only one of &lt;code&gt;SNOWPACK_IN/OUT&lt;/code&gt; will be in each section:&lt;br&gt;</help>
	</parameter>
	<parameter type="helptext" wrap="true" section="Sections">
		<help>&lt;code&gt;&amp;lt;parameter key=&quot;IO_FORMAT&quot; type=&quot;alternative&quot;&amp;gt;&lt;br&gt;
			&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;lt;section name=&quot;INPUT&quot;/&amp;gt;&lt;br&gt;
			&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;lt;section name=&quot;OUTPUT&quot;/&amp;gt;&lt;br&gt;
			&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;lt;option value=&quot;CSV&quot;/&amp;gt;&lt;br&gt;
			&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;lt;option value=&quot;SNOWPACK_IN&quot;&amp;gt;&lt;br&gt;
			&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;lt;section name=&quot;Input&quot;/&amp;gt;&lt;br&gt;
			&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;lt;/option&amp;gt;&lt;br&gt;
			&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;lt;option value=&quot;SNOWPACK_OUT&quot;&amp;gt;&lt;br&gt;
			&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;lt;section name=&quot;Output&quot;/&amp;gt;&lt;br&gt;
			&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;lt;/option&amp;gt;&lt;br&gt;
			&amp;lt;/parameter&amp;gt;&lt;/code&gt;&lt;br&gt;</help>
	</parameter>
243
	<frame caption="References" color="sl_blue" section="sections">
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
		<parameter type="helptext" wrap="true">
			<help>We have already encountered include files, which must be valid XML documents (they at least need a parent node). The following mechanism to reference nodes from within the document is also always available:</help>
		</parameter>
		<parameter type="helptext" wrap="true">
			<help>Reference to another part of the file:&lt;br&gt;</help>
		</parameter>
		<parameter type="helptext" wrap="true">
			<help>&lt;code&gt;&amp;lt;&lt;b&gt;reference name&lt;/b&gt;=&quot;METEOPARAMETERS&quot;/&amp;gt;&lt;/code&gt;&lt;br&gt;</help>
		</parameter>
		<parameter type="helptext" wrap="true">
			<help>The node being referenced:&lt;br&gt;</help>
		</parameter>
		<parameter type="helptext" wrap="true">
			<help>&lt;code&gt;&amp;lt;&lt;b&gt;parametergroup name&lt;/b&gt;=&quot;METEOPARAMETERS&quot;&amp;gt;&lt;br&gt;
				&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;lt;option value=&quot;TA&quot;/&amp;gt;&lt;br&gt;
				&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;lt;option value=&quot;RH&quot;/&amp;gt;&lt;br&gt;
				&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;lt;option value=&quot;VW&quot;/&amp;gt;&lt;br&gt;
				&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;lt;option value=&quot;DW&quot;/&amp;gt;&lt;br&gt;
				&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;lt;option value=&quot;P&quot;/&amp;gt;&lt;br&gt;
				&amp;lt;/parametergroup&amp;gt;&lt;/b&gt;</help>
		</parameter>
	</frame>
266

267
	<!-- FRAMES -->
268

269
270
	<parameter type="label" label="&lt;h3&gt;Frames&lt;/h3&gt;" color="sl_blue">
	<section name="Frames" color="sl_blue"/>
271
272
273
274
275
	</parameter>
	<parameter type="helptext" wrap="true">
		<section name="Frames"/>
		<help>&lt;b&gt;Frames&lt;/b&gt; are a visual grouping element. Most of the panels in this help file are enclosed in frames.&lt;br&gt;</help>
	</parameter>
276
	<frame caption="This is a frame" color="sl_blue">
277
278
279
280
281
		<section name="Frames"/>
		<parameter type="helptext" wrap="true">
			<help>Frames can be colored with &lt;code&gt;color&lt;/code&gt; for the box and text, and &lt;code&gt;background_color&lt;/code&gt; for the background color.&lt;br&gt;</help>
		</parameter>
		<parameter type="helptext" wrap="true">
282
			<help>&lt;code&gt;&amp;lt;frame caption=&quot;This is a frame&quot; color=&quot;#268bd2&quot;&amp;gt;&lt;/code&gt;</help>
283
284
		</parameter>
	</frame>
285
286
287
	<parameter type="helptext" wrap="true" section="Frames">
		<help>&lt;br&gt;With the following code a frame can be given a background color:&lt;br&gt;</help>
	</parameter>
288
	<frame caption="Note" color="#002b36" background_color="#657b83">
289
290
		<section name="Frames"/>
		<parameter type="helptext" wrap="true">
291
			<help>From now on we trust that you have an understanding of how it works and can look up the XML nodes for what is shown here in the help file XMLs (&lt;code&gt;./inishell --dump_help&lt;/code&gt;), as well as in the shipped application XMLs. If you like a panel, just look for its key in the XML to see how it's done. (This help file is written in valid application syntax, only with a strong focus on help texts.) So from now on, the notation in here is shortened a bit.&lt;br&gt;</help>
292
293
		</parameter>
		<parameter type="helptext" wrap="true" section="Frames">
294
			<help>&lt;code&gt;&amp;lt;frame caption=&quot;Note&quot; color=&quot;#002b36&quot; background_color=&quot;#657b83&quot;&amp;gt;&lt;/code&gt;</help>
295
296
		</parameter>
	</frame>
297
298
299
	<parameter type="spacer" height="50" section="Frames"/>
	<frame caption="Options for all panels" color="sl_blue">
		<section name="Frames" color="sl_blue"/>
300
301
302
303
304
305
306
307
		<parameter type="helptext" wrap="true">
			<help>The following options work with most input panels:&lt;ul&gt;
				&lt;li&gt;Setting that this parameter is non-optional with &lt;code&gt;optional=&quot;false&quot;	&lt;/code&gt;&lt;/li&gt;
				&lt;li&gt;Setting the default value via &lt;code&gt;default=&quot;default_value&quot;&lt;/code&gt;&lt;/li&gt;
				&lt;li&gt;Setting a different &lt;code&gt;caption&lt;/code&gt; and styling it&lt;/li&gt;
				&lt;/ul&gt;</help>
		</parameter>
	</frame>
308

309
	<!-- HELPTEXTS and LABELS -->
310

311
312
	<parameter type="label" label="&lt;h3&gt;Helptext and Label elements&lt;/h3&gt;" color="sl_blue">
		<section name="Help and Labels" color="sl_blue"/>
313
314
315
316
317
	</parameter>
	<parameter type="helptext" wrap="true" section="Help and Labels">
		<help>A &lt;b&gt;&amp;lt;helptext&amp;gt;&lt;/b&gt; panel displays a piece of information. So does a &lt;b&gt;&amp;lt;label&amp;gt;&lt;/b&gt;, which is usually associated with an INI key but can also be set separately. They can be used in the following ways.</help>
	</parameter>
	<parameter type="helptext" wrap="true" help="Helptexts can also have tooltips.">
318
		<section name="Help and Labels"/>
319
		<help>&lt;br&gt;This is a standalone help text. It will also display a tool tip if you hover the mouse over it, like all panels can.&lt;br&gt;Per default, the tooltip is set to the panel's key. To add a custom tooltip to a panel, specify the &lt;code&gt;help&lt;/code&gt; attribute in the panel itself:&lt;br&gt;&lt;code&gt;key="INPUT_TEXT" type="text" help="An input text"&lt;/code&gt;</help>
320
321
322
323
324
325
326
327
	</parameter>
	<parameter key="INPUT_TEXT" type="text" size="large" section="Help and Labels" help="An input text">
		<help>A parameter's help is shown to the right if a &lt;code&gt;&amp;lt;help&amp;gt;&lt;/code&gt; node is given as a child to the parameter node. It can span as many lines as you wish, and you can use HTML styling, e. g. &amp;lt;br&amp;gt; for a line break.</help>
	</parameter>
	<parameter type="helptext" section="Help and Labels" nowrap="true">
		<help>For standalone help texts you can supply either &lt;code&gt;wrap=&quot;true&quot;&lt;/code&gt; to enable dynamic wrapping (like it is done in this whole help file), or disable line wrapping with &lt;code&gt;wrap=&quot;false&quot;&lt;/code&gt;.</help>
	</parameter>
	<parameter type="helptext" wrap="true" section="Help and Labels">
328
		<help>You can use &lt;b&gt;&lt;font color=&quot;#268bd2&quot;&gt;HTML styling&lt;/font&gt;&lt;/b&gt; in all helptexts (see the &lt;font color=&quot;#268bd2&quot;&gt;Styling&lt;/font&gt; tab), otherwise they will have a uniform look.</help>
329
330
331
332
	</parameter>
	<parameter key="SOME_NAME_WE_DONT_WANT_TO_SHOW_DIRECTLY" label="Pick a name: " type="text" section="Help and Labels">
		<help>It is possible to give a &lt;code&gt;&amp;lt;label&amp;gt;&lt;/code&gt; attribute to the panel node in order to display a different label than the INI key itself:&lt;br&gt;&lt;code&gt;&amp;lt;parameter key=&quot;SOME_NAME_WE_DONT_WANT_TO_SHOW_DIRECTLY&quot; caption=&quot;Pick a name: &quot; type=&quot;text&quot;&amp;gt;&lt;/code&gt;</help>
	</parameter>
333
334
335
336
337
338
339
340
341
342
343
	<frame caption="Label width" section="Help and Labels">
		<parameter type="helptext" wrap="true">
			<help>A key label's width is either a fixed with (the first "column"), or if that is not enough it is extended to fit the content. Sometimes however you will have a list of INI keys that get scrambled together this way, alternating between a fixed and dynamic width. For this reason you can set to use the second "column" by specifying &lt;code&gt;longlabel="true"&lt;/code&gt;.</help>
			<parameter key="LONG_TEXT" type="text" label="This is a long description of an INI key:" longlabel="true">
				<help>Here we have specified long label texts.</help>
			</parameter>
			<parameter key="NORMAL_TEXT" type="text" longlabel="true">
				<help>This way the longer text can be aligned with the short one.</help>
			</parameter>
		</parameter>
	</frame>
344

345
	<!-- TEXTFIELD -->
346
347
	<parameter type="label" label="&lt;h3&gt;Text input&lt;/h3&gt;" color="sl_blue">
		<section name="Text" color="sl_blue"/>
348
349
350
351
352
	</parameter>
	<parameter type="helptext" wrap="true" section="Text">
		<help>A &lt;b&gt;&amp;lt;text&amp;gt;&lt;/b&gt; panel has the following options:&lt;ul&gt;
			&lt;li&gt;&lt;code&gt;size=&quot;small/medium/large&quot;&lt;/code&gt;&lt;/li&gt;
			&lt;li&gt;It will automatically scan for arithmetic expressions, environment variables, and INI keys in the shown form.&lt;/li&gt;
353
			&lt;li&gt;Or, setting &lt;code&gt;lenient="true"&lt;/code&gt; will make it parse for arithmetic expressions without pre- and postfix&lt;/li&gt;
354
355
			&lt;li&gt;&lt;code&gt;validate=&quot;your_regex&quot;&lt;/code&gt; Regular expression to check text against&lt;/li&gt;
			&lt;li&gt;&lt;code&gt;placeholder=&quot;placeholder text&quot;&lt;/code&gt; Set a placeholder text for empty text field&lt;/li&gt;
356
357
			&lt;/ul&gt;&lt;br&gt;</help>
	</parameter>
358
	<frame caption="Text input" section="Text">
359
		<parameter key="SHORT_TEXT" type="text"/>
360
		<parameter key="ENVIRONMENT_VARIABLE" type="text" default="${env:USER}">
361
362
			<help>key=&quot;ENVIRONMENT_VARIABLE&quot; type=&quot;text&quot; size=&quot;medium&quot; default=&quot;${env:USER}&quot;</help>
		</parameter>
363
364
		<parameter key="FORMULA" label="Enter arithmetic expression:" type="text" size="large" default="${{pi+sin(10)}}"/>
		<parameter key="INVALID_FORMULA" label="An invalid formula:" type="text" size="large" default="${{20+x-}}"/>
365
		<parameter key="COORDINATES" type="text" default="latlon(46.81206, 9.84721)"/>
366
		<parameter key="FREE_FORMULA" label="Formula without pre/postfix:" type="text" size="large" lenient="true" default="60*60*24"/>
367
368
369
		<parameter key="REGEX_VALIDATION" label="Check against regular expression:" type="text" validate="^(\w+)(\d+)$" default="STATION1">
			<help>validate=&quot;^(\w+)(\d+)$&quot; (word plus number)</help>
		</parameter>
370
		<parameter key="PLACEHOLDER_TEXT" label="Display placholder for empty text:" type="text" placeholder="&lt;station ID&gt;"/>
371
372
373
		<parameter type="helptext" wrap="true" section="Text">
			<help>One more "expression" can be checked: INI key names of the opened application: &lt;i&gt;${SECTION::KEY_NAME}&lt;/i&gt;</help>
		</parameter>
374
	</frame>
375

376
	<!-- FILE INPUT -->
377

378
379
	<parameter type="label" label="&lt;h3&gt;File input&lt;/h3&gt;" color="sl_blue">
		<section name="Files" color="sl_blue"/>
380
381
382
383
384
385
386
387
388
	</parameter>
	<parameter type="helptext" wrap="true" section="files">
		<help>A &lt;b&gt;&amp;lt;file&amp;gt;&lt;/b&gt; resp. &lt;b&gt;&amp;lt;path&amp;gt;&lt;/b&gt; panel has the following options:&lt;ul&gt;
			&lt;li&gt;Calling it &lt;code&gt;file&lt;/code&gt; or &lt;code&gt;path&lt;/code&gt; will allow to either choose a file or a directory.&lt;/li&gt;
			&lt;li&gt;When the optional &lt;code&gt;mode=&quot;input/output&quot;&lt;/code&gt; attribute is given, a few more checks are enabled about the file (e. g. an input file should exist).&lt;/li&gt;
			&lt;li&gt;Remember that these are warnings only, and the INI file will save normally.&lt;/li&gt;
			&lt;li&gt;You can supply &lt;code&gt;&amp;lt;option extension=&quot;File type (*.ext)/&amp;gt;&quot;&lt;/code&gt; child nodes to filter for these file extensions.&lt;/li&gt;
			&lt;/ul&gt;&lt;br&gt;</help>
	</parameter>
389
	<frame caption="File input" section="files">
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
		<parameter key="INPUT_FILE" type="file" mode="input" default="default.txt">
			<help>&lt;code&gt;type=&quot;file&quot; mode=&quot;input&quot; default=&quot;default.txt&quot;&lt;/code&gt;</help>
		</parameter>
		<parameter key="FILE_INPUT" label="An input file with label:" type="file" mode="input" optional="false">
			<help>&lt;code&gt;type=&quot;file&quot; mode=&quot;input&quot; optional=&quot;false&quot;&lt;/code&gt;</help>
		</parameter>
		<parmeter key="OUTPUT_PATH" type="path" mode="output"/>
		<parameter key="FILE_OUTPUT" type="file" mode="output">
			<option extension="HTML files (*.html *.htm)"/>
			<option extension="Text Files (*.log *.txt *.dat)"/>
			<help>&amp;lt;parameter key=&quot;FILE_OUTPUT&quot; type=&quot;file&quot; mode=&quot;output&quot;&amp;gt;&lt;br&gt;
				&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;lt;option extension=&quot;HTML files (*.html *.htm)&quot;/&amp;gt;&lt;br&gt;
				&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;lt;option extension=&quot;Text Files (*.log *.txt *.dat)&quot;/&amp;gt;</help>
		</parameter>
	</frame>

	<!-- NUMBERS -->
407

408
409
	<parameter type="label" label="&lt;h3&gt;File input&lt;/h3&gt;" color="sl_blue">
		<section name="Numbers" color="sl_blue"/>
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
	</parameter>
	<parameter type="helptext" wrap="true" section="numbers">
		<help>A &lt;b&gt;&amp;lt;number&amp;gt;&lt;/b&gt; panel has the following options:&lt;ul&gt;
			&lt;li&gt;format=&quot;integer/integer+/decimal&quot;&lt;/li&gt;
			&lt;li&gt;&lt;code&gt;min, max&lt;/code&gt; for minimum and maximum of the value&lt;/li&gt;
			&lt;li&gt;&lt;code&gt;sign=&quot;true&quot;&lt;/code&gt; to always show the sign of the number&lt;/li&gt;
			&lt;li&gt;&lt;code&gt;unit=&quot;my_unit&quot;&lt;/code&gt; to display a unit next to the number&lt;/li&gt;
			&lt;li&gt;&lt;code&gt;notoggle=&quot;true&quot;&lt;/code&gt; to hide the toggle button for expression evaluation&lt;/li&gt;
			&lt;li&gt;&lt;code&gt;wrap=&quot;true&quot;&lt;/code&gt; to have the arrow buttons wrap around the limits&lt;/li&gt;
			&lt;li&gt;If you set a valid expression as default value, the panel will start in this state&lt;/li&gt;
			&lt;/ul&gt;&lt;br&gt;</help>
	</parameter>
	<parameter key="INTEGER" type="number" format="integer" section="numbers"/>
	<parameter key="POSITIVE_INTEGER" type="number" format="integer+" section="numbers">
		<help>&lt;code&gt;type=&quot;number&quot; format=&quot;integer+&quot;&lt;/code&gt;</help>
	</parameter>
	<parameter key="FLOATING_POINT" type="number" format="decimal" section="numbers"/>
	<parameter key="EXPRESSION" type="number" default="${{60*60*24}}" section="numbers"/>
	<parameter key="LIMIT_INTEGER" label="Integer with limits and circular wrapping:" type="number" format="integer" min="12" max="24" wrap="true" section="numbers">
		<help>&lt;code&gt;label=&quot;Integer...&quot; type=&quot;number&quot; format=&quot;integer&quot; min=&quot;12&quot; max=&quot;24&quot; wrap=&quot;true&quot;&lt;/code&gt;</help>
	</parameter>
	<parameter key="ANNOTATED_DOUBLE" sign="true" unit="days" precision="1" type="number" default="1.5" section="numbers" notoggle="true"/>
432

433
	<!-- DATETIME -->
434

435
436
	<parameter type="label" label="&lt;h3&gt;Datetime&lt;/h3&gt;" color="sl_blue">
		<section name="Datetime" color="sl_blue"/>
437
	</parameter>
438
439
	<parameter type="helptext" wrap="true" section="datetime">
		<help>A &lt;code&gt;&lt;b&gt;&amp;lt;datetime&amp;gt;&lt;/b&gt;&lt;/code&gt; panel allows users to more comfortably enter a date and/or time.</help>
440
	</parameter>
441
	<parameter type="helptext" wrap="true" section="datetime">
442
443
444
445
		<help>It has the following options:&lt;ul&gt;
			&lt;li&gt;format=&quot;format_string&quot;&lt;/li&gt;
			&lt;/ul&gt;&lt;br&gt;</help>
	</parameter>
446
	<frame caption="Date / time selection" section="datetime">
447
448
449
450
451
452
		<parameter key="DATETIME" type="datetime">
			<help>Date and time in default ISO formatting.</help>
		</parameter>
		<parameter key="TIME" type="datetime" format="hh:mm:ss" default="12:00:00">
			<help>Time only via &lt;code&gt;format="hh:mm:ss"&lt;/code&gt;.</help>
		</parameter>
453
		<parameter type="helptext" wrap="true">
454
455
456
457
			<help>Format strings can be anything Qt recognizes, default is ISO: &lt;code&gt;yyyy-MM-ddThh:mm:ss&lt;/code&gt;</help>
		</parameter>
	</frame>

458
	<!-- CHECKBOX -->
459

460
461
	<parameter type="label" label="&lt;h3&gt;Checkbox&lt;/h3&gt;" color="sl_blue">
		<section name="Checkbox" color="sl_blue"/>
462
463
	</parameter>
	<parameter type="helptext" wrap="true" section="checkbox">
464
		<help>A &lt;code&gt;&lt;b&gt;&amp;lt;checkbox&amp;gt;&lt;/b&gt;&lt;/code&gt; panel stands for a &lt;code&gt;TRUE/FALSE&lt;/code&gt; choice. It will also handle &lt;code&gt;t/f&lt;/code&gt; and &lt;code&gt;0/1&lt;/code&gt; alternatively.&lt;br&gt;. It can have child panels that are displayed when the box is checked.</help>
465
	</parameter>
466
	<frame caption="Checkboxes" section="checkbox">
467
468
469
470
		<parameter key="RESAMPLING" type="checkbox">
			<help>&amp;lt;parameter key=&quot;RESAMPLING&quot; type=&quot;checkbox&quot;&amp;gt;&lt;br&gt;</help>
		</parameter>
		<parameter type="helptext" wrap="true">
471
			<help>You can set the key label and caption independently. Different to other panels if you omit a label it will be hidden, not display the key (because this is more common - supply in "label" if wanted).&lt;br&gt;</help>
472
		</parameter>
473
474
475
476
477
		<parameter key="RESAMPLING" caption="Enable resampling" type="checkbox">
			<help>&lt;code&gt;caption=&quot;Enable resampling&quot;&lt;/code&gt;</help>
		</parameter>
		<parameter key="RESAMPLING" label="Perform resampling?" caption="Enable resampling" type="checkbox">
			<help>&lt;code&gt;label=&quot;Perform resampling?&quot; caption=&quot;Enable resampling&quot;&lt;/code&gt;</help>
478
		</parameter>
479
480
481
482
483
484
485
486
		<parameter key="CHECKBOX_CHILD" caption="Check to view child panels" type="checkbox">
			<option>
				<parameter key="CHECKBOX_TEXT" type="text"/>
				<parameter key="CHECKBOX_NUM" type="number"/>
			</option>
			<help>A checkbox with child panels.</help>
		</parameter>
	</frame>
487
	<frame caption="Source code for a Checkbox with children" section="checkbox" color="sl_blue">
488
489
490
491
492
493
494
495
		<parameter type="helptext">
			<help>&amp;lt;parameter key="CHECKBOX_CHILD" caption="Check to view child panels" type="checkbox"&amp;gt;&lt;br&gt;
				&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;lt;option&amp;gt;&lt;br&gt;
				&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;lt;parameter key="CHECKBOX_TEXT" type="text"/&amp;gt;&lt;br&gt;
				&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;lt;parameter key="CHECKBOX_NUM" type="number"/&amp;gt;&lt;br&gt;
				&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;lt;/option&amp;gt;&lt;br&gt;
				&amp;lt;/parameter&amp;gt;</help>
		</parameter>
496
	</frame>
497

498
	<!-- ALTERNATIVE -->
499

500
501
	<parameter type="label" label="&lt;h3&gt;Alternative panel&lt;/h3&gt;" color="sl_blue">
		<section name="Alternative" color="sl_blue"/>
502
503
504
505
	</parameter>
	<parameter type="helptext" wrap="true" section="alternative">
		<help>An &lt;code&gt;&lt;b&gt;&amp;lt;alternative&amp;gt;&lt;/b&gt;&lt;/code&gt; panel is a dropdown list the user can select from. It can show child panels for each individual item.&lt;br&gt;</help>
	</parameter>
506
	<frame caption="Alternatives">
507
		<section name="Alternative"/>
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
		<parameter key="ALTERNATIVE_MANDATORY" type="alternative" optional="false">
			<option value="TRUE"/>
			<option value="FALSE"/>
		</parameter>
		<parameter key="OPTIONAL_ALTERNATIVE" type="alternative">
			<option value="on"/>
			<option value="off"/>
		</parameter>
		<parameter key="FREE_ALTERNATIVE" type="alternative" editable="true">
			<option value="item A"/>
			<option value="item B"/>
		</parameter>
		<parameter key="DIFFERENT_ALTERNATIVE" label="A verbose list of options:" type="alternative">
			<option value="value 1" caption="This is value one"/>
			<option value="value 2" caption="This is value two"/>
523
			<help>A dropdown menu can have items that are labelled different to their value. Check the &lt;font color=&quot;#268bd2&quot;&gt;Preview&lt;/font&gt; to verify this.</help>
524
525
526
527
528
529
530
		</parameter>
		<parameter key="CHILD_ALTERNATIVE" label="Dropdown with child elements:" type="alternative">
			<option value="textbox_option">
				<parameter key="OPTION_TEXTBOX" type="text"/>
				<parameter key="OTHER_TEXTBOX" type="text"/>
			</option>
			<option value="number_option">
531
				<parameter key="OPTION_NUMBER" type="number"/>
532
533
534
535
536
537
538
539
540
541
542
			</option>
			<option value="nested_option">
				<parameter key="NESTED_ALTERNATIVE" type="alternative">
					<option value="no_child" default="true"/>
					<option value="nested_child">
						<parameter key="NESTED_NUMBER" type="number"/>
					</option>
				</parameter>
			</option>
		</parameter>
	</frame>
543
	<frame caption="Child options" color="sl_blue">
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
		<section name="Alternative"/>
		<parameter type="helptext" wrap="true">
			<help>An &lt;code&gt;Alternative&lt;/code&gt; panel is one of the panels that can have child panels depending on which option is selected.&lt;br&gt;</help>
		</parameter>
		<parameter key="METEO" type="alternative">
			<help>Choose your input path with meteo data</help>
			<option value="SMET">
				<parameter key="METEOPATH" type="path" mode="input"><help>Item help</help></parameter>
			</option>
			<option value="SNOWPACK"/>
		</parameter>
		<parameter type="helptext" wrap="true">
			<help>&lt;code&gt;&lt;br&gt;&amp;lt;parameter key=&quot;METEO&quot; type=&quot;alternative&quot;&amp;gt;&lt;br&gt;
				&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;lt;help&amp;gt;&quot;...&quot;&amp;lt;/help&amp;gt;&lt;br&gt;
				&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;lt;option value=&quot;SMET&quot;&amp;gt;&lt;br&gt;
				&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;lt;parameter key=&quot;METEOPATH&quot; type=&quot;path&quot; mode=&quot;input&quot;&amp;gt;&amp;lt;help&amp;gt;...&amp;lt;/help&amp;gt;&amp;lt;/parameter&amp;gt;&lt;br&gt;
				&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;lt;/option&amp;gt;&lt;br&gt;
				&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;lt;option value=&quot;SNOWPACK&quot;/&amp;gt;&lt;br&gt;
				&amp;lt;/parameter&amp;gt;&lt;/code&gt;</help>
		</parameter>
	</frame>
565
	<frame caption="Performance savings mode" color="sl_blue" section="alternative">
566
567
		<parameter type="helptext" wrap="true" section="alternative">
			<help>Normally, all child panels of an Alternative panel are always built. This way, a user can switch between some different modes of operation and still keep their settings for all of them - even if currently unused.&lt;br&gt;
568
				Some dropdown lists however are so complex that if they control a large number of INI keys, building all child panels for each setting has a considerable impact on performance. For this reason you can use the &lt;i&gt;pre-generate=false&lt;/i&gt; mode which will tell &lt;i&gt;INIshell&lt;/i&gt; to only build child panels on first request, i. e. when the list item is first selected. This mode is best suited for:&lt;ul&gt;
569
570
571
572
				&lt;li&gt;Settings that will not change often. E. g. in &lt;i&gt;MeteoIO&lt;/i&gt; it will hardly ever be necessary to configure more than one input plugin at the same time and switch between them frequently.&lt;/li&gt;
				&lt;li&gt;Settings where it is a reasonable assumption that the parent key is always found before child settings. E. g. in &lt;i&gt;MeteoIO&lt;/i&gt; we make request that TA::FILTERS1 = MIN must be found before TA::ARG1::MIN so that the child panels are built.&lt;/li&gt;
				&lt;li&gt;Settings where you can set the default value to the parent that needs children.&lt;/li&gt;
				&lt;/ul&gt;
573
			Remember that unknown INI keys are transported to the output, so they will be there in any case, but they won't interact with the GUI if the pre-generate=false mode is not suitable for this setting. Enable this mode by setting &lt;code&gt;pre-generate="false"&lt;/code&gt; in the Alternative's attributes.</help>
574
575
		</parameter>
	</frame>
576
	<parameter type="helptext" wrap="true" section="alternative">
577
578
		<help>&lt;br&gt;Note: Giving a default argument to an Alternative panel, the decimals should match the given precision.</help>
	</parameter>
579

580
	<!-- CHOICE -->
581

582
583
	<parameter type="choice" label="&lt;h3&gt;Choice&lt;/h3&gt;" color="sl_blue">
		<section name="Choice" color="sl_blue"/>
584
585
586
587
	</parameter>
	<parameter type="helptext" wrap="true" section="choice">
		<help>A &lt;code&gt;&lt;b&gt;&amp;lt;choice&amp;gt;&lt;/b&gt;&lt;/code&gt; panel displays a list of checkboxes. Each of the checkboxes may show additional child panels, which can themselves show more options.&lt;br&gt;</help>
	</parameter>
588
	<frame caption="Multiple choice" section="choice">
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
		<parameter key="GENERATORS" type="choice" label="Data generators:">
			<o value="STD_PRESS"><help>Choose from a list of options.</help></o>
			<option value="CST">
				<parameter key="@::CST::VALUE" type="number"/>
				<help>For each of them, more configuration panels may be shown.</help>
			</option>
			<option value="SIN">
				<parameter type="horizontal">
					<option>
						<parameter key="@::SIN::TYPE" type="alternative" optional="false">
							<option value="yearly" help="Yearly period"/>
							<option value="daily" help="Daily period" default="true"/>
						</parameter>
					</option>
					<o><parameter key="@::SIN::MAX" type="number"/></o>
					<o><parameter key="@::SIN::PHASE" type="number"/></o>
				</parameter>
				<help>Sinusoidal generator.</help>
			</option>
		</parameter>
	</frame>
610
	<frame caption="Source code" color="sl_blue" section="choice">
611
612
613
614
615
		<parameter type="helptext" wrap="true">
			<help>A &lt;code&gt;Choice&lt;/code&gt; panel has the following syntax. In each &lt;code&gt;option&lt;/code&gt; child node, you can start with a &lt;code&gt;parameter&lt;/code&gt; or &lt;code&gt;frame&lt;/code&gt; again. You can nest as many panels as you wish.&lt;br&gt;</help>
		</parameter>
		<parameter type="helptext" wrap="true">
			<help>&lt;code&gt;&amp;lt;parameter key=&quot;CHOICE&quot; type=&quot;choice&quot;&amp;gt;&lt;br&gt;
616
				&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;lt;option value=&quot;...&quot;&amp;gt;&lt;br&gt;
617
618
619
620
				&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;lt;parameter ... /&amp;gt;&lt;br&gt;
				&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;lt;parameter ... /&amp;gt;&lt;br&gt;
				&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;...&lt;br&gt;
				&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;lt;/option&amp;gt;&lt;br&gt;
621
				&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;lt;option value=&quot;...&quot;&amp;gt;&lt;br&gt;
622
623
624
625
626
627
				&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;...&lt;br&gt;
				&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;lt;/option&amp;gt;&lt;br&gt;
				&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;....&lt;br&gt;
				&amp;lt;/parameter&amp;gt;&lt;/code&gt;</help>
		</parameter>
	</frame>
628

629
	<!-- CHECKLIST -->
630

631
632
	<parameter type="label" label="&lt;h3&gt;Checklist&lt;/h3&gt;" color="sl_blue">
		<section name="Checklist" color="sl_blue"/>
633
634
635
636
	</parameter>
	<parameter type="helptext" wrap="true" section="checklist">
		<help>A &lt;code&gt;&lt;b&gt;&amp;lt;checklist&amp;gt;&lt;/b&gt;&lt;/code&gt; panel has exactly the same syntax as a &lt;code&gt;&lt;b&gt;&amp;lt;choice&amp;gt;&lt;/b&gt;&lt;/code&gt; panel. Depending on the number of options a &lt;code&gt;choice&lt;/code&gt; panel can be more compact.&lt;br&gt;</help>
	</parameter>
637
	<frame caption="Checklist" section="checklist">
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
		<parameter key="GENERATORS" type="checklist">
			<help>Choose a data generator</help>
			<o value="STD_PRESS"></o>
			<option value="CST">
				<parameter key="@::CST::VALUE" type="number"/>
			</option>
			<option value="SIN">
				<parameter type="horizontal">
					<option>
						<parameter key="@::SIN::TYPE" type="alternative" optional="false">
							<option value="yearly" help="Yearly period"/>
							<option value="daily" help="Daily period" default="true"/>
						</parameter>
					</option>
					<o><parameter key="@::SIN::MAX" type="number"/></o>
					<o><parameter key="@::SIN::PHASE" type="number"/></o>
				</parameter>
			</option>
		</parameter>
	</frame>
658

659
	<!-- SELECTORS -->
660

661
662
	<parameter type="label" label="&lt;h3&gt;Selectors&lt;/h3&gt;" color="sl_blue">
		<section name="Selectors" color="sl_blue"/>
663
664
	</parameter>
	<parameter type="helptext" wrap="true" section="selectors">
665
		<help>Sometimes, you need to transport a parameter name or other text to the INI key. For example, you could need to set the INI key &lt;code&gt;TA::FILTER1 = MIN&lt;/code&gt;. We don't want an extra filter for each meteo parameter so we can use a shortcut for it: &lt;code&gt;%::FILTER1&lt;/code&gt;. This is what a &lt;code&gt;&lt;b&gt;&amp;lt;selector&amp;gt;&lt;/b&gt;&lt;/code&gt; does. If you don't disable it the user can also enter free text.&lt;br&gt;</help>
666
	</parameter>
667
	<frame caption="Parameter selector" section="selectors">
668
669
670
671
672
673
674
675
676
		<parameter key="FILTER" type="selector">
			<option value="TA"/>
			<option value="RH"/>
			<parameter key="%::FILTER" type="alternative" template="true">
				<o value="MIN"/>
				<o value="MAX"/>
			</parameter>
		</parameter>
	</frame>
677
	<frame caption="Source code" color="sl_blue" section="selectors">
678
679
680
681
682
683
684
685
686
687
688
689
690
691
		<parameter type="helptext" wrap="true">
			<help>A &lt;code&gt;Selector&lt;/code&gt; panel has the following syntax. In a list of &lt;code&gt;option&lt;/code&gt; tags you supply the texts that the &lt;code&gt;Selector&lt;/code&gt; should offer. Additionally, to actually activate a panel for the parameters you must give the &lt;code&gt;&lt;b&gt;template=&quot;true&quot;&lt;/b&gt;&lt;/code&gt; attribute for the panel you want to construct with the parameter:&lt;br&gt;</help>
		</parameter>
		<parameter type="helptext" wrap="true">
			<help>&lt;code&gt;&amp;lt;parameter key=&quot;FILTER&quot; type=&quot;selector&quot;&amp;gt;&lt;br&gt;
				&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;lt;option value=&quot;TA&quot;/&amp;gt;&lt;br&gt;
				&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;lt;option value=&quot;RH&quot;/&amp;gt;&lt;br&gt;
				&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;lt;parameter key=&quot;%::FILTER&quot; type=&quot;alternative&quot; template=&quot;true&quot;&amp;gt;&lt;br&gt;
				&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;lt;o value=&quot;MIN&quot;/&amp;gt;&lt;br&gt;
				&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;lt;o value=&quot;MAX&quot;/&amp;gt;&lt;br&gt;
				&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;lt;/parameter&amp;gt;&lt;br&gt;
				&amp;lt;/parameter&amp;gt;&lt;/code&gt;</help>
		</parameter>
	</frame>
692
	<frame section="selectors">
693
694
695
696
697
698
699
700
701
		<parameter key="FILTER" type="selector" editable="false">
			<option value="TA"/>
			<option value="RH"/>
			<parameter key="%::FILTER" type="alternative" template="true">
				<o value="MIN"/>
				<o value="MAX"/>
			</parameter>
			<help>&lt;code&gt;key=&quot;FILTER&quot; type=&quot;selector&quot; editable=&quot;false&quot;&lt;/code&gt;</help>
		</parameter>
702
703
704
705
706
		<parameter key="TEXTMODE" label="No dropdown:" type="selector" textmode="true">
			<parameter key="%::TEXTMODE" type="text" optional="false" template="true">
				<help>&lt;code&gt;type=&quot;selector&quot; textmode=&quot;true&quot;&lt;/code&gt;</help>
			</parameter>
		</parameter>
707
		<parameter key="TEXTMODE2" label="No dropdown, placeholder text:" type="selector" textmode="true" placeholder="&lt;ID&gt;">
708
709
710
711
			<parameter key="%::TEXTMODE" type="text" optional="false" template="true">
				<help>&lt;code&gt;type=&quot;selector&quot; textmode=&quot;true&quot;&lt; placeholder=&quot;true&quot;/code&gt;</help>
			</parameter>
		</parameter>
712
	</frame>
713

714
	<!-- REPLICATORS -->
715

716
717
	<parameter type="label" label="&lt;h3&gt;Replicators&lt;/h3&gt;" color="sl_blue">
		<section name="Replicators" color="sl_blue"/>
718
719
720
721
	</parameter>
	<parameter type="helptext" wrap="true" section="replicators">
		<help>A &lt;code&gt;&lt;b&gt;&amp;lt;replicator&amp;gt;&lt;/b&gt;&lt;/code&gt; panel can enumerate an INI key. For example, it can construct &lt;code&gt;STATION1, STATION2, ...&lt;/code&gt; from the INI key &lt;code&gt;STATION#&lt;/code&gt;.&lt;br&gt;</help>
	</parameter>
722
	<frame caption="Replicator" section="replicators">
723
724
725
726
727
728
729
		<parameter type="helptext" wrap="true">
			<help>A replicator is activated by taking any other panel and adding the &lt;code&gt;&lt;b&gt;replicate=&quot;true&quot;&lt;/b&gt;&lt;/code&gt; attribute.&lt;br&gt;</help>
		</parameter>
		<parameter key="STATION#" type="text" replicate="true">
			<help>&amp;lt;parameter key=&quot;STATION#&quot; type=&quot;text&quot; replicate=&quot;true&quot;/&amp;gt;</help>
		</parameter>
	</frame>
730

731
	<!-- RASTERS -->
732

733
734
	<parameter type="label" label="&lt;h3&gt;Rasters&lt;/h3&gt;" color="sl_blue">
		<section name="Rasters" color="sl_blue"/>
735
736
737
738
	</parameter>
	<parameter type="helptext" wrap="true" section="rasters">
		<help>You have the &lt;code&gt;&lt;b&gt;&amp;lt;horizontal&amp;gt;&lt;/b&gt;&lt;/code&gt; and the &lt;code&gt;&lt;b&gt;&amp;lt;grid&amp;gt;&lt;/b&gt;&lt;/code&gt; identifiers at your disposal to create rastered layouts. This is most useful if a panel such as an Alternative panel displays child panels that should not use up too much space.&lt;br&gt;</help>
	</parameter>
739
	<parameter type="label" label="Horizontal layout of 3 items:" color="black">
740
		<section name="rasters"/>
741
742
743
744
745
746
	</parameter>
	<parameter type="horizontal" section="rasters">
		<o><frame color="black" background_color="black"/></o>
		<o><frame color="black" background_color="black"/></o>
		<o><frame color="black" background_color="black"/></o>
	</parameter>
747
	<parameter type="label" label="Regular 2x2 grid:" color="sl_red" section="rasters"/>
748
749
	<parameter type="grid" section="rasters">
		<option row="1" column="1">
750
			<frame color="sl_red" background_color="sl_red"/>
751
		</option>
752
753
754
		<o r="1" c="2"><frame color="sl_red" background_color="sl_red"/></o>
		<o r="2" c="1"><frame color="sl_red" background_color="sl_red"/></o>
		<o r="2" c="2"><frame color="sl_red" background_color="sl_red"/></o>
755
	</parameter>
756
	<parameter type="label" label="Irregular grid:" color="sl_green" section="rasters"/>
757
	<parameter type="grid" section="rasters">
758
759
760
		<o r="1" c="2"><frame color="sl_green" background_color="sl_green"/></o>
		<o r="2" c="1"><frame color="sl_green" background_color="sl_green"/></o>
		<o r="2" c="2"><frame color="sl_green" background_color="sl_green"/></o>
761
	</parameter>
762
	<parameter type="label" label="Spanning elements:" color="sl_cyan" section="rasters"/>
763
	<parameter type="grid" section="rasters">
764
765
		<o r="1" c="1"><frame color="sl_cyan" background_color="sl_cyan"/></o>
		<o r="1" c="2"><frame color="sl_cyan" background_color="sl_cyan"/></o>
766
767
		<option row="2" column="1" colspan="2">
			<parameter type="helptext">
768
				<help>This is a helptext that spans two columns. The spanning only takes action if the space is actually needed.&lt;br&gt;</help>
769
770
771
			</parameter>
		</option>
	</parameter>
772
773
	<frame caption="Options for all panels" color="sl_blue">
		<section name="rasters" color="sl_blue"/>
774
775
		<parameter type="helptext" wrap="true">
			<help>The following options work with most input panels:&lt;ul&gt;
776
				&lt;li&gt;You can use &lt;b&gt;&lt;code&gt;&amp;lt;o&amp;gt;&amp;lt;/o&amp;gt;&lt;/code&gt;&lt;/b&gt; and &lt;b&gt;&lt;code&gt;&amp;lt;h&amp;gt;&amp;lt;/h&amp;gt;&lt;/code&gt;&lt;/b&gt; tags in many panels with options as a shortcut. This is mostly useful for gridded layouts; check the source for the grids above to see more shortcuts.&lt;/li&gt;
777
778
				&lt;/ul&gt;</help>
		</parameter>
779
		<parameter type="spacer" height="100" section="rasters"/>
780
		<parameter type="helptext" wrap="true" section="rasters">
Michael Reisecker's avatar
Michael Reisecker committed
781
			<help>There is also a &lt;b&gt;spacer&lt;/b&gt; element available with the &lt;code&gt;width&lt;/code&gt; and &lt;code&gt;height&lt;/code&gt; attributes to put some space between elements, like it was done here.</help>
782
783
		</parameter>
	</frame>
784
785
	<frame caption="Substitutions" color="sl_blue">
		<section name="rasters" color="sl_blue"/>
786
787
788
789
790
791
792
793
794
795
796
797
798
		<parameter type="helptext" wrap="true">
			<help>You can use the &lt;code&gt;@&lt;/code&gt; sign to reference the grid's key:</help>
		</parameter>
		<parameter key="FILTER" type="horizontal">
			<option>
				<parameter key="@::MIN" type="number">
					<help>&lt;code&gt;&amp;lt;parameter key=&quot;FILTER&quot; type=&quot;horizontal&quot;&amp;gt;&lt;br&gt;
						&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;nbsp;&amp;lt;o&amp;gt;&amp;lt;parameter key=&quot;@::MIN&quot; type=&quot;number&quot;&amp;gt;&amp;lt;/parameter&amp;gt;&amp;lt;/o&amp;gt;&lt;br&gt;
						&amp;lt;/parameter&amp;gt;&lt;/code&gt;</help>
				</parameter>
			</option>
		</parameter>
	</frame>
799

800
	<!-- STYLING -->
801

802
803
	<parameter type="label" label="&lt;h3&gt;Text styling&lt;/h3&gt;" color="sl_blue">
		<section name="Style" color="sl_blue"/>
804
805
	</parameter>
	<parameter type="helptext" wrap="true" section="style">
806
		<help>Help texts and labels can be styled in various ways. The  following attributes are often available: &lt;code&gt;font, font_size, bold, italic, color, underline, background_color&lt;/code&gt;. If there is a second element to style, for example the caption of a check box (in addition to the label), this is referenced with &lt;code&gt;caption_color, caption_font, ...&lt;/code&gt;. A list of extra named colors is available in &lt;i&gt;src/main/colors.cc&lt;/i&gt; that is derived from the solarized palette.&lt;br&gt;</help>
807
	</parameter>
808
	<frame caption="Text styling" color="sl_blue">
809
810
		<section name="Style"/>
		<parameter label="BOLD_KEY" type="text" bold="true">
811
			<help>&lt;code&gt;&amp;lt;parameter label=&quot;BOLD_KEY&quot; type=&quot;label&quot; bold=&quot;true&quot;&amp;gt;&lt;/code&gt;</help>
812
		</parameter>
813
		<parameter label="ITALIC_KEY" type="label" italic="true"/>
814
		<parameter label="COLORED_KEY" type="label" color="sl_red"/>
815
		<parameter label="UNDERLINED_KEY" type="label" underline="true"/>
816
		<parameter label="A_DIFFERENT_FONT" type="label" font="Times New Roman"/>
817
		<parameter type="spacer" height="50"/>
818
819
820
		<parameter key="CHECKBOX" type="checkbox" color="darkgreen" caption="enabled" caption_color="#00adad">
			<help>&lt;code&gt;&amp;lt;parameter key=&quot;CHECKBOX&quot; type=&quot;checkbox&quot; color=&quot;darkgreen&quot; caption=&quot;enabled&quot; caption_color=&quot;#00adad&quot;/&amp;gt;&lt;/code&gt;</help>
		</parameter>
821
		<parameter type="spacer" height="50"/>
822
823
		<frame key="yellow" caption="Colored frames" color="sl_red">
			<frame color="black" background_color="sl_yellow">
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
				<parameter key="PROMINENT_KEY" type="text"/>
			</frame>
			<parameter type="horizontal">
				<o><frame key="red" color="red"/></o>
				<o><frame key="blue" color="lightblue"/></o>
				<o><frame key="magenta" background_color="magenta"/></o>
				<o><frame key="green" background_color="green"/></o>
			</parameter>
		</frame>
		<parameter type="spacer" height="50"/>
		<parameter type="horizontal">
			<option>
				<parameter key="CHECKLIST_ITEMS" type="checklist" color="darkred">
					<option value="an item" bold="true"/>
					<option value="another item" italic="true"/>
					<option value="third item" color="red"/>
				</parameter>
			</option>
			<o><parameter type="spacer" w="50"/></o>
			<option>
				<parameter key="CHOICE" type="choice" color="darkred">
					<option value="check one" italic="true"/>
846
					<option value="check two" color="sl_blue"/>
847
848
849
850
851
852
853
					<option value="check three" underline="true"/>
				</parameter>
			</option>
			<o><parameter type="spacer" w="50"/></o>
			<option>
				<parameter key="ALTERNATIVE_ITEMS" type="alternative" color="darkred">
					<option value="first option" bold="true"/>
854
					<option value="second option" italic="true"/>
855
856
857
858
859
					<option value="third option" color="red"/>
				</parameter>
			</option>
		</parameter>
	</frame>
860
861
862
863
864
865
	<parameter type="helptext" wrap="true" section="style">
		<help>&lt;br&gt;Plus, within help texts and labels you can use HTML styling in the text itself like it is done throughout this document. Just watch out that you usually need to escape XML characters:&lt;br&gt;</help>
	</parameter>
	<frame caption="HTML styling" section="style">
		<parameter type="label" label="&lt;h4&gt;This is a &amp;lt;h4&amp;gt; header given in a Label&lt;/h4&lt;br&gt;and a &amp;lt;hr&amp;gt; line below&lt;br&gt;&lt;hr&gt;"/>
	</frame>
866

867
</inishell_config>