NAME
AssistantFrames - GUI-Class to build an assistant-like line of
frames on the Macintosh that resembles the standard OS
assistants.
SYNOPSIS
This uses a static predefined sequence. This is easy to set up
and easy to process.
use Mac::AssistantFrames;
my $assist = Mac::AssistantFrames->new();
$assist->addToSequence(sub { $assist->startFrame("title", "description"); });
$assist->addToSequence(sub { $assist->yesnoFrame("title", "description"); });
$assist->addToSequence(sub { $assist->finishFrame("title", "description"); });
my $res = $assist->processSequence();
if (defined($res)) {
print join(":", @$res);
}
This is for handcoded sequencing through dialogs - this allows a
flexible sequence and shows some more of the methods.
use Mac::AssistantFrames;
my $assist = Mac::AssistantFrames->new();
while ($assist->running()) {
my $last = $assist->getLastFrame();
if ($last eq "<empty>") {
$assist->startFrame("title", "description");
} elsif ($last eq "<start>") {
$assist->constantFrame("dlg1", "title",
"description", "value");
} elsif ($last eq "dlg1") {
$assist->singleSelectionFrame("dlg2", "title",
"description",
["v1", "v2", "v3"]);
} elsif ($last eq "dlg2") {
$assist->constantHiddenFrame("dlg3", "value");
} elsif ($last eq "dlg3") {
$assist->finishFrame("title", "description");
}
}
if ($assist->getLastFrame eq "<finish>") {
print $assist->joinedAnswersr(":"), "\n";
} else {
print "aborted\n";
}
DESCRIPTION
This Module implements simple assistant style frames for
MacPerl. You can use it if you need to ask the user some
questions in sequence to accomplish a task. This could be done
with one dialogbox, too. But the assistant approach is often
easier to understand, especially if the user doesn't know much
about the subject at hand. This is the case most often with
configuration of new software packages, where the user has to be
given much more detailed descriptions of what to do as would fit
on a simple dialog.
The AssistantFrame allows backward navigation in case the user
erred on some of his answers. It allows complete backwind of the
frames (abortion of the process) and it has a uniform
userinterface that resembles a lot the Mac-style assistants.
CLASS METHODS
new()
This constructor creates a new frame sequence object.
Version()
This method returns the version of the module.
METHODS
running()
This checks if the assistant object is in running state. If
the "<start>" frame is aborted, this is reset to 0. If the
"<finish>" frame is accepted, this is reset to 0.
backupOne()
This method backs up one frame. This is internally used, you
seldom have to invoke it yourself.
continueOne(name, value)
This method adds a successfull frame to the sequence. This
is used internally, so you shouldn't need to call this
yourself.
abort([text])
This method stops the assistant. If "text" is given, it
creates an alert dialog. If it is not given, the assistant
is just canceled. This can be used to react on errors in a
assistant processing.
standardAction(name, dlg)
This method is internally used to process the events from
the dialog. Just ignore it.
getLastFrame()
This method returns the last frame the user completed. This
is needed to allow backing up and sequencing correctly. If
the sequence of frames is empty, it returns "<empty>".
getLastFrameRaw()
This method is used to get the last frame, as is
getLastFrame. Only difference: getLastFrameRaw delivers the
frame-name in "raw" format - names of hidden constant
elements is bracketed in []. This function is used
internally to distinguish frames from constants.
getLastAnswer()
This returns the last answer given. It is usefull to make
frames dependend on older frames.
getAnswers()
This returns a reference to the array of the answer-strings.
joinedAnswers(sep)
This returns a string created by joining all answers
together, separated by sep.
getNumAnswers()
This returns the number of accumulated answers.
addToSequence(closure)
This adds the closure to the sequence array of the
assistant. The sequence array allows a simple processing of
a static sequence of frames.
processSequence()
This processes the sequence array and returns a reference to
the array of answers.
FRAMES
startFrame(title, description)
This frame has the special name "<start>". It must be the
first frame in the sequence and should give the user a short
introduction into the task at hand. The user can only abort
the sequence if he is at this frame and backs up, or by
closing the window of the current frame (this can be done in
any frame). The startframe produces the empty string as
value. Any other frame can take over the rule of the
startframe by giving it the name "<start>".
finishFrame(title, description)
This frame has the special name "<finish>". It must be the
last frame in the sequence and should give the user a
description of the effect this whole sequence would have if
completed. It produces the empty string as value. Any frame
can take over the rule of the finish-frame by giving it the
name "<finish>".
constantFrame(dlg, title, description, value)
This frame is just an informational Message that is
associated with a constant value. It is often needed if you
have to give more detailed descriptions.
constantHiddenFrame(value)
This frame is no frame - it is just a constant value that is
spliced into the answer list. This might be needed by your
application, if you want to construct a string out of the
answer-list with join. If backed-up, this frame is ignored.
textEntryFrame(dlg, title, description, value)
This frame allows the entry of free text into a frame. This
text is then delivered as answer.
yesnoFrame(dlg, title, description)
This frame asks a simple yes-no question. This may be used
for asking for optional parts of the assistant. It delivers
a Y or a N as answer.
radioFrame(dlg, title, description, values, labels [, offset])
This frame presents a selection using radio buttons. Only
one value can be selected. This is usefull for small
selections. The strings from labels are used for the frame,
the strings from values are delivered in the answer. The
offset is used for the positioning of the elements.
singleSelectFrame(dlg, title, description, [val1, val2, val3])
This frame allows a single selection out of a list of
values. This should be used if there are more than 5 values
to choose from, or if the number of values is not known at
compiletime.
COPYRIGHT
Copyright 1998, Georg Bauer
This library is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
AVAILABILITY
The latest version of this library is likely to be available
from:
http://www.westfalen.de/hugo/mac/
If there are problems with this library, just drop a note to:
Georg_Bauer@muensterland.org
=cut