The Autopackage API

User interaction

Autopackage is designed to be frontend-independent. 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

NameParameters
outputFail <MESSAGE>
outputStatus <STATUS>
outputTest <WHAT>
outputTestFail
outputTestPass
progressBar <CURRENT> <MAX> <LABEL> [COMPRESS = 0]

Details

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


outputStatus
Syntax: outputStatus <STATUS>
STATUS: A status message.
Show the current status of the installation.
Match against __outputStatus_status variable if it exists. If the variable is different from the current call then display status message.
Example:
outputStatus "Installing plugin for foobar..."
copyFiles libplugin.so /usr/lib/foobar/plugins


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"


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


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


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