The Autopackage API

Table of Contents / Public library / User interaction

User interaction

Autopackage is designed to be frontend-independant. That means what happens during the installation can be displayed in many ways, including in a GUI and in a console, depending on which frontend is being used. These functions provide an easy way to communicate with the frontend.

Functions in this category

outputTest<WHAT>
outputStatus<STATUS>
outputTestPass
outputTestFail
outputFail<MESSAGE>
progressBar<CURRENT> <MAX> <LABEL> [COMPRESS = 0]
interactString<NAME> <DEFAULT> <MESSAGE>
interactPath<NAME> <DEFAULT> <MESSAGE>
waitForInteractions
get<NAME>

Details

outputTest
Syntax: outputTest <WHAT>
WHAT: A short description of the test currently being performed.
Tells the user that the installation is currently testing for something.
This function is designed to be used within package prep scripts. It will be called for you by require() when using the skeletons framework, so should be rarely used explicitly, but you can also use it in your own scripts. It will indicate to the user that their system is currently being tested. It should be followed by a call to either outputTestFail, outputTestPass or outputTestRecommend.
The output will be of the form "Checking for $1.... " - ie you should not provide the preamble, instead you should provide a succint description of what is being tested. For instance, a good string to use would be "ability to play Ogg Vorbis files", and bad string to use would be "Can we play Ogg files?". Remember: don't phrase it as a question, instead as a description.
Also remember to try and keep the description simple. Don't use jargon unless it's really necessary. That way, if a test fails and the system cannot fix the problem itself, the users will find it easier to do so themselves.
See also: outputTestPass() and outputTestFail().
Example: 
outputTest "GTK User Interface toolkit"
outputTest "Ogg Vorbis playback capabilities"
outputTest "ability to connect to the internet"

outputStatus
Syntax: outputStatus <STATUS>
STATUS: A status message.
Show the current status of the installation.
Example: 
outputStatus "Installing plugin for foobar..."
copyFiles libplugin.so /usr/lib/foobar/plugins

outputTestPass
Syntax: outputTestPass
Tells the user that the last test passed. See also: outputTest() and outputTestFail().
Example: 
outputTest "foobar"		# Frontend displays: "Checking for foobar..."
if [[ ! -f /usr/bin/foobar ]]; then
	outputTestFail		# -> "Checking for foobar... FAILED"
else
	outputTestPass		# -> "Checking for foobar... PASSED"
fi

outputTestFail
Syntax: outputTestFail
Tells the user that the last test failed. See also: outputTest() and outputTestPass().
Example: 
outputTest "foobar"		# Frontend displays: "Checking for foobar..."
if [[ ! -f /usr/bin/foobar ]]; then
	outputTestFail		# -> "Checking for foobar... FAILED"
else
	outputTestPass		# -> "Checking for foobar... PASSED"
fi

outputFail
Syntax: outputFail <MESSAGE>
MESSAGE: A short message describing the problem.
Tells the frontend that a fatal error has occurred. The frontend will tell the user that the installation has failed after the install script has exited.
Please note that you should to call outputTestFail() before calling this function, if you've just called outputTest().
Example: 
outputTest "a working installation of foobar"
if [[ -f /var/broken ]]; then
	# The installation of foobar on this system is broken!!!
	outputTestFail
	outputFail "Foobar is broken!"
else
	outputTestPass
fi

progressBar
Syntax: progressBar <CURRENT> <MAX> <LABEL> [COMPRESS = 0]
LABEL: A label associated to this progress.
COMPRESS: Whether to compress the progress bar. 1 = compress, 0 = don't compress. See description.
MAX: A number specifying the maximum value of the progress. This must be greater than 0.
CURRENT: A number specifying the current value of the progress. This must be greater than 0.
Display a progress bar. If CURRENT is equal to MAX, then that means the progress has finished.
If MAX is a very big value (> 100), and your progress bar changes very fast, pass 1 to the COMPRESS argument. This will reduce the number of calls to the frontend, which reduces CPU usage. You normally shouldn't have to care about this argument, and should only use it in exceptional cases. The progress bar that's shown when extracting files is such a case.
Example: 
progressBar 1 10 "Copying files"     # 10% [=>       ] Copying files
progressBar 5 10 "Copying files"     # 50% [====>    ] Copying files
progressBar 10 10 "We're done"       # 100%[=========] We're done

interactString
Syntax: interactString <NAME> <DEFAULT> <MESSAGE>
NAME: An internal name for this interaction.
DEFAULT: A default value.
MESSAGE: The message to display.
Request the frontend for interaction. The frontend may display a dialog box with the message MESSAGE, and ask the user for input. DEFAULT is used as the default value in the input box, and will also be used when the user presses Cancel.

The value will not be passed back immediately. Instead, it is stored in a queue. Interactions will be performed when waitForInteractions() is called. After that, you can get the value for NAME using get(). See get() for an example about how to do interactions.

IMPORTANT NOTE: Do not expect the user to input anything! Depending the frontend (such as the GTK+ frontend in silent mode), the user may not be asked anything at all! Therebefore the default value must always be the safest, most sensible value!

If you need information that *requires* user interaction, then consider moving that code into the main application, not the installation (remember that Unix/Linux are multi-user systems; different users may input different things).
See also: interactPath().

interactPath
Syntax: interactPath <NAME> <DEFAULT> <MESSAGE>
NAME: An internal name for this interaction.
DEFAULT: A default value.
MESSAGE: The message to display.
Request the frontend for directory interaction. The frontend may display a directory selection box with the message MESSAGE, and ask the user to select a directory. DEFAULT is used as the default directory in the directory selection box, and will also be used when the user presses Cancel.

The value will not be passed back immediately. Instead, it is stored in a queue. Interactions will be performed when waitForInteractions() is called. After that, you can get the value for NAME using get(). See get() for an example about how to do interactions.

IMPORTANT NOTE: Do not expect the user to input anything! Depending the frontend (such as the GTK+ frontend in silent mode), the user may not be asked anything at all! Therebefore the default value must always be the safest, most sensible value!

If you need information that *requires* user interaction, then consider moving that code into the main application, not the installation (remember that Linux is a multi-user system; different users may input different things).
See also: interactPath().

waitForInteractions
Syntax: waitForInteractions
Tell the frontend to perform interactions. See also: interactString() and interactPath(). See get() for an example about interactions.

get
Syntax: get <NAME>
NAME: An interaction's name, as passed to interactString() and interactPath().
Get the value for interaction NAME. This function can only be called after waitForInteractions() has been called. The result will be printed on stdout.
Example: 
interactString USERNAME "Joe Sixpack" "What is your name?"
interactPath FAVDIR "$HOME" "What is your favorite directory?"

waitForInteractions
name=`get USERNAME`
favDir=`get FAVDIR`

outputStatus "Your name is $name!"
outputStatus "Your favorite directory is $favDir!"

Last update: 2/4/2004