library/wizard/doc/Progress.html
<html><head>
<title>Progress bar hand-written documentation</title></head><body>
<H2>Everything you ever wanted to know about progress bar but were
afraid to ask</H2>
<p>
I found out that module Progress although having thorough autogenerated
documentation is often hard to use or misused. And people are shied to
ask. So I decided to create this small HOWTO and EXAMPLES file.
</p>
<p>
<b>Q: What is progress bar and how can I use it in my YaST2 module?</b><br>
<b>A:</b> Progress bar is a graphical widget that sweetens user's time spent
by the computer while waiting for some action to finish. In YaST2 you should
use module Progress. Start with adding import "Progress"; into your code.
Let's look at an example:<pre>
import "Progress";
Progress::New (
"Complex Progress Bar",
"Initial progress caption",
20,
[ "Stage 1", "Stage 2", "Stage 3", ],
[ "Stage 1...", "Stage 2...", "Stage 3...", "Finished", ],
"Help text"
);
</pre>
This create progress bar that looks like this:<br>
<img src="screenshots/progress1.png"><br>
The lines "Stage 1", "Stage 2", Stage 3" are called <b>stages</b>.
The 20 in Progress::New call has nothing to do with stages, it is length
of the progress bar widget at the bottom of the screen. Now let's try:<pre>
Progress::NextStage ();</pre> As you see, there is an arrow by the text
"Stage 1" and progress bar widget label changed to "Stage 1...". Now you
could understand what stages are good for. Try this: <pre>
Progress::NextStep ();</pre> Do not worry, this does not re-install your
linux box. It will only advance progress bar widget value. Now you should
understand, that there can be other number of progress bar stages and steps.
<br>
<br>
<b>Q: What's the Help text good for?</b><br>
<b>A:</b> Some people like them. But usually noone reads. But anyway. If you
want to set the help texts in one call with the progress bar setup, you may
use the last parameter. If you want to leave help text untouched, supply "" or
nil. If you want to clear it, pass " " (space).
<br>
<br>
<b>Q: This progress bar is too complex. I can live with just progress bar
widget without stages. Do I have to construct screen on my own?</b><br>
<b>A:</b> No. Use call of Simple instead if New. <pre>
Progress::Simple (
"Simple progress bar",
"Progress bar title",
100,
"Help text");
</pre>
As you see, there are no stages so only calls NextStep, Step and Title apply
here.
<br>
<br>
<b>Q: Wow, that's exactly what I wanted. Are there any other tweaking
possibilities?</b><br>
<b>A:</b> Of course. You can stay without progress bar widget - may have just
stages. Just pass 0 as length argument in function New.
<br>
<br>
<b>Q: Anything else?</b><br>
<b>A:</b> No. But if you have any suggestion, feel free to ask. BTW: keep in
mind strange "feature" of libyui. If you pass an empty string as progress bar
title in call of New or Simple, progress bar widget will have NO title (even
if you try to change it latter). See
<a href="http://bugzilla.suse.de/show_bug.cgi?id=10258">Bugzilla 10258</a> and
do not forget that if it works today it need not work tommorrow.
<br>
<br>
<b>Q: I want a function that goes to the next step and changes title. Please
change function NextStep to take title as an argument. </b><br>
<b>A:</b> No. Use <pre>Progress::NextStep ();
Progress::Title (_("My new title"));</pre>I hate changing existing interface.
If you can not live without it, mail me, I will create other function.
<br>
<br>
<b>Q: Are there any conventions when creating package startup or finish
progress bar?</b><br>
<b>A:</b> We are trying to compose them. As we are going to have an
autoinstallation, we should keep some unified structure of packages. First
attempt to define such structure is package skeleton. Please look at it and use
similar structure in your packages. You should define function Read and Write
that will handle the progress bar themselves. If the caller of one of these
functions does not want the progress bar, it just calls<pre>
boolean orig = Progress::set (false);
MyPackage::Write (``{return false; });
Progress::set (orig);
</pre>
<br>
<br>
<b>Q: Hey, it is ugly!</b><br>
<b>A:</b> I know. Do you have a better idea?
<br>
<br>
<b>Q: Is there some autogenerated documentation for Progress?</b><br>
<b>A:</b> <a href="autodocs/Progress.html">autodocs/Progress.html</a>
<br>
<br>
<b>Q: This progress bar is ugly and has terrible API. I will use my
own.</b><br>
<b>A:</b> You should not. Please keep in mind that with this one we can change
look and feel of all progress bars simply by replacing module Progress.
<br>
<br>
<b>Q: I have a question that is not covered by this FAQ. I found a bug. I want
a feature. What should I do?</b><br>
<b>A:</b> Feel free to ask at any e-mail address you find in this text.
<br>
<br>
<b>Q: What's Superior Progress bar?</b><br>
<b>A:</b> It's a way to have a progress bar in a progress bar. It looks like
this:<br> <img src="screenshots/progress2.png"><br>
I think it can be used in some cases, for example at the end of installation,
when settings of configuration packages are saved. Example of code:<pre>
{
import "Progress";
import "Wizard";
define SubProgress (string title) ``{
Progress::New ("Progress bar: " + title, "", 303,
[ "Stage 1", "Stage 2", "Stage 3", ],
[ "Stage 1 ...", "Stage 2 ...", "Stage 3 ...", "Finished", ],
"Help Text"
);
integer i = 0;
while (i > 301) {
if (0 == i % 100)
Progress::NextStage ();
Progress::NextStep ();
i = i + 1;
}
Progress::Finish ();
}
list<string> subs = ["Network", "Printer", "Sound", "Modem", "TV Card", ];
Wizard::CreateDialog ();
Progress::OpenSuperior ("Saving configuration...", subs);
foreach (string i, subs, ``{
Progress::StepSuperior ();
SubProgress (i);
});
Progress::StepSuperior ();
Progress::CloseSuperior ();
UI::CloseDialog ();
}
</pre>
</p>
<hr>
Petr Blahos <a href="mailto:pblahos@suse.cz">pblahos@suse.cz</a>
</body></html>