1 <listitem id="command_version">
4 <parameter>number</parameter>
7 This exchanges with the frontend the protocol version
8 number that is being used. The current version is
9 2.1. Versions in the 2.x series will be
10 backwards-compatible. You may specify the protocol version
11 number you are speaking. The frontend will return the version
12 of the protocol it speaks. If the version you specify is too
13 low, this command will return the numeric return code
14 <literal>30</literal>.
17 <listitem id="command_capb">
20 <parameter>capabilities</parameter>
23 This exchanges with the frontend a list of supported capabilities
24 Capabilities both the frontend and your confmodule support may be
25 used; the capabilities supported by the frontend are returned by
28 <title>Currently used capabilities</title>
32 <entry>capability</entry>
33 <entry>description</entry>
40 Backing up to a previous step is supported.
44 <entry>multiselect</entry>
46 The multiselect data type is supported. You do not need to
47 check this capability if you depend on any modern version
56 <listitem id="command_settitle">
59 <parameter>template</parameter>
62 You can use this command to set a title in the
63 frontend. This may appear in different ways, depending on the
64 frontend being used, for example it might change the title
65 of the frontend's window. If you don't specify anything, a
66 title will automatically be generated.
69 Using a template has the advantage that titles are translatable
70 and that they can be maintained in the same place as other text
74 <listitem id="command_title">
77 <parameter>string</parameter>
80 Similar to SETTITLE, but takes a string instead of a template as
81 parameter. Consequence is that the title will not be translatable,
82 unless some other mechanism (like gettext) is used.
85 <listitem id="command_stop">
90 This command tells the frontend you're done talking to it. Typically
91 the frontend can detect the termination of your program and this
92 command is not necessary.
95 <listitem id="command_input">
98 <parameter>priority</parameter>
99 <parameter>question</parameter>
102 This tells the frontend to display a question (or other type of
103 item) to the user. <parameter>question</parameter> is the name of the
104 item to display, all other information about the item is retrieved
105 from the templates described previously.
106 <parameter>priority</parameter> is how important it is that the
107 user be prompted. The frontend need only ask this question if the
108 priority is high enough. The question is not displayed until a go
109 command is given. This allows us to ask multiple questions in a single
110 screen. Once a question has been displayed to the user and the user has
111 provided input, the frontend will set the
112 <literal>seen</literal> flag.
116 Note that the frontend decides if the user is actually
117 prompted or not. If the user has already answered a
118 question, they are normally not asked it again even if
119 input is called again. And if the user is ignoring low
120 priority items, they will not see them. In either of
121 these cases, this command returns the numeric return code
122 <literal>30</literal>.
125 <listitem id="command_beginblock">
130 <listitem id="command_endblock">
135 Some frontends are able to display a number of items to
136 the user at once. To do this, they need to be given blocks
137 of input commands, enclosed in the BEGINBLOCK and ENDBLOCK
138 commands. Blocks can be nested and very advanced frontends
139 may use this as a user interface hint.
143 There is an implicit block around any set of INPUT commands
144 that are not enclosed in an explicit block.
148 <listitem id="command_go">
153 Shows the current set of accumulated items to the user and lets
154 them fill in values, etc. If the backup capability is supported
155 and the user indicates they want to back up a step, this command
156 returns the numeric return code <literal>30</literal>.
159 <listitem id="command_clear">
164 Clears the accumulated set of INPUT commands without displaying
168 <listitem id="command_get">
170 GET <parameter>question</parameter>
173 Ask the frontend to tell you how the user answered a question. The
174 value is returned to you.
177 <listitem id="command_set">
180 <parameter>question</parameter>
181 <parameter>value</parameter>
184 Set the answer of a question to a value.
187 <listitem id="command_reset">
189 RESET <parameter>question</parameter>
192 Reset the question to its default value. This includes
193 resetting flags to their defaults.
196 <listitem id="command_subst">
199 <parameter>question</parameter>
200 <parameter>key</parameter>
201 <parameter>value</parameter>
204 Questions (and other items) can have substitutions embedded in
205 their descriptions (and, currently in their choices fields). These
206 substitutions look like "<literal>${key}</literal>". When the
207 question is displayed, the substitutions are replaced with their
208 values. This command can be used to set the value of a
212 <listitem id="command_fget">
215 <parameter>question</parameter>
216 <parameter>flag</parameter>
219 Questions (and other items) can have flags associated with them. The
220 flags have a value of "<literal>true</literal>" or
221 "<literal>false</literal>". This command returns
225 <listitem id="command_fset">
228 <parameter>question</parameter>
229 <parameter>flag</parameter>
230 <parameter>value</parameter>
233 This sets the state of a flag on a question. Valid
234 states for the flag are "<literal>true</literal>" and
235 "<literal>false</literal>".
238 One common flag is the
239 "<literal>seen</literal>" flag. It is normally only set if
240 a user already seen a question.
241 Typically, frontends only display questions to users if they have the
242 seen flag set to "false". Sometimes you want the user to see a
243 question again -- in these cases you can set the seen flag to
244 false to force the frontend to redisplay it.
247 Note that as a special convenience behavior, frontends will
248 redisplay already seen questions if the question was first seen by
249 the user in the same confmodule run. This makes it easy for a
250 confmodule to back up to previous questions without having to reset
254 <listitem id="command_metaget">
257 <parameter>question</parameter>
258 <parameter>field</parameter>
261 This returns the value of any field of a question (the description, for
265 <listitem id="command_register">
268 <parameter>template</parameter>
269 <parameter>question</parameter>
272 This creates a new question that is bound to a
273 template. By default each template has an associated
274 question with the same name. However, any number of
275 questions can really be associated with a template, and
276 this lets you create more such questions.
279 <listitem id="command_unregister">
282 <parameter>question</parameter>
285 This removes a question from the database.
288 <listitem id="command_purge">
293 Call this in your postrm when your package is
294 purged. It removes all templates and questions your
295 package has generated.