\begindata{text,538429096}
\textdsversion{12}
\template{be2guide}
\define{global
}
\define{underline
menu:[Font~1,Underline~41]
attr:[Flags Underline Int Set]}
\define{index
menu:[Title,Index~91]
attr:[FontFace Italic Int Set]}
\define{indexi
menu:[Title,InvisibleIndex~92]
attr:[Script PreviousScriptMovement Point -2]
attr:[Flags Hidden Int Set]
attr:[FontFace Italic Int Set]}
\define{fixedtext
menu:[Region~4,Fixedtext]
attr:[Justification LeftJustified Point 0]
attr:[FontFace FixedFace Int Set]
attr:[FontFamily AndyType Int 0]
attr:[FontSize ConstantFontSize Point 10]}
\define{fixedindent
menu:[Region~4,Fixedindent]
attr:[LeftMargin LeftMargin Cm 83230]
attr:[Justification LeftJustified Point 0]
attr:[FontFace FixedFace Int Set]
attr:[FontFamily AndyType Int 0]
attr:[FontSize ConstantFontSize Point 10]}
\define{paramname
menu:[Font~1,Paramname]
attr:[FontFace Italic Int Set]}
\formatnote{\chapter{Message}}
\indexi{Message} \indexi{User messages}
\indexi{Dialogues}
The class \italic{message} is the interface for displaying information to
the user and asking the user questions. \
Related documentation includes: \
\begindata{link,539697832}
Datastream version: 3
$ANDREWDIR/doc/atk/basics/msghndlr.doc
0
0
\begindata{link,539697832}
Datastream version: 2
msghndlr
2
black
white
\enddata{link,539697832}
\enddata{link,539697832}
\view{linkview,539697832,8,0,0}msghndlr.doc - manages the display and
interactions of messages posted in a window
\section{Quick reference list for }message
\fixedtext{void \bold{message_}Advice }\fixedindent{(struct view
*\paramname{view}, enum message_Preference \paramname{pref});} \
\fixedtext{int \bold{message_}AskForStringCompleted }\fixedindent{(struct
view *\paramname{view}, int \paramname{priority}, char
*\paramname{prompt},
char *\paramname{defaultString}, char *\paramname{buffer}, int
\paramname{bufferSize}, struct keymap *\paramname{keystate}, procedure
\paramname{completionProc}, procedure \paramname{helpProc}, long
\paramname{functionData}, int \paramname{flags});} \
\fixedtext{int \bold{message_}AskForString }\fixedindent{(struct view
*\paramname{view}, int \paramname{priority}, char *\paramname{prompt},
char
*\paramname{defaultString}, char *\paramname{buffer}, int
\paramname{bufferSize});} \
\fixedtext{boolean \bold{message_}Asking }\fixedindent{(struct view
*\paramname{view});} \
\fixedtext{void \bold{message_}CancelQuestion }\fixedindent{(struct view
*\paramname{view});} \
\fixedtext{int \bold{message_}DeleteCharacters }\fixedindent{(struct view
*\paramname{view}, int \paramname{pos}, int \paramname{len});} \
\fixedtext{int \bold{message_}DisplayString }\fixedindent{(struct view
*\paramname{view}, int \paramname{priority}, char *\paramname{string});}
\
\fixedtext{int \bold{message_}GetCurrentString }\fixedindent{(struct view
*\paramname{view}, char *\paramname{buffer}, int
\paramname{bufferSize});} \
\fixedtext{int \bold{message_}GetCursorPos }\fixedindent{(struct view
*\paramname{view});} \
\fixedtext{int \bold{message_}InsertCharacters }\fixedindent{(struct view
*\paramname{view}, int \paramname{pos}, char *\paramname{string}, int
\paramname{len});} \
\fixedtext{int \bold{message_}MultipleChoiceQuestion
}\fixedindent{(struct
view *\paramname{view}, int \paramname{priority}, char
*\paramname{prompt},
long \paramname{defaultChoice}, long *\paramname{result}, char
**\paramname{choices}, char *\paramname{abbrevKeys});} \
\fixedtext{int \bold{message_}SetCursorPos }\fixedindent{(struct view
*\paramname{view}, int \paramname{pos});} \
\section{Overview of message}
There are two types of messages that the class \italic{message} provides:
display and question. A display message simply delivers a message to
the
user. A question message allows you to display a message that prompts
the
user for a string. You can provide help and completion functions as
well
as special key processing to effect more sophisticated question prompting
and answering facilities. There is also a question method that allows
you
to display a dialog box with multiple choice questions. Finally, the
class
\italic{message} provides auxiliary methods that allow you to query the
status of a message operation, and to modify the user's input during a
question operation. \indexi{Message++Displaying a string}
\indexi{Message++Asking a question}
The message methods all operate on a \italic{view}. The class
\italic{message} passes message display requests up the view tree from
the
given view, looking for a handler of type "message" (see the
\italic{view_WantHandler} routine in the section, View). Unless otherwise
noted, the \italic{view} can be \smaller{NULL}, in which case the
\italic{message} will choose a default message handler. The current
implementation does this by using the toplevel handler in the last window
that experienced user input. \indexi{Message++View tree}
The class \italic{message} provides an abstraction that is open to many
methods of implementation. The Andrew Toolkit currently provides a
standard message line and dialog box interface in the class
\italic{frame}.
However, the system is open to alternative implementations of the
abstraction. \
\indexi{Dialog boxes}
Messages have a \italic{priority} that determines whether the system
displays the message in the message line or in a dialog box. If the
\italic{priority} is 0, the system will display it in the message line;
if
100, the system will display it in a dialog box. The system uses a user
preference, \italic{*.DialogPriority}, to determine how to display
\italic{priorities} with values between 0 and 100. The default value of
\italic{*.DialogPriority} is 50, meaning that the system will display
messages with \italic{priorities} less than 50 in the message line; above
50, in a dialog box. \indexi{Message++Priority}
The class \italic{message} provides application programmers with an
interface to services offered by message handlers. Message handlers are
instances of a subclass of \italic{msghandler}. The class
\italic{msghandler} defines the interface that a message service must
conform to. You do not need to know about the details of the class
\italic{msghandler} in order to use the class \italic{message}. \
\begindata{bp,539388792}
Version 2
n 0
\enddata{bp,539388792}
\view{bpv,539388792,0,0,0}
\section{Display messages} \
\paragraph{Displaying a string} \indexi{ \italic{message_DisplayString}}
\indexi{Message++Displaying a string}
\example{int message_DisplayString(v, priority, string)
struct view *v;
int priority;
char *string;} \
\leftindent{\bold{Class procedure description.}
\italic{message_DisplayString} displays a message \italic{string} in the
view \italic{v}. The \italic{priority} determines whether the message
text
shows up in a message line or a dialog box. The \italic{priority} scale
is
from 0 to 100, with 100 being the highest priority. \
\bold{Return value.} In case of error, -1; otherwise a nonnegative
value.
It is rather pointless to check error returns on this function because it
will be impossible to announce the error to the user. \
\bold{Example.} The following code displays a message in the message
line,
assuming that the view hierarchy includes an interaction manager, a
frame,
a message line, and a textview: \
\example{
struct textview *txtv;
message_DisplayString (txtv, 0, "Search failed.");
}
}
\section{Question messages
} \paragraph{Asking for a string} \indexi{ \italic{message_AskForString}}
\indexi{Message++Asking a question}
\example{int message_AskForString (v, priority, prompt,
defaultString,buffer, bufferSize)
struct view *v;
int priority;
char *prompt, *defaultString, *buffer;
int bufferSize;} \
\leftindent{\bold{Class procedure description.}
\italic{message_AskForString} prompts the user for a plain character
string by displaying \italic{prompt} for view \italic{v}. The string is
returned in the area pointed to by the parameter \italic{buffer} and is
guaranteed not to exceed \italic{bufferSize} characters. The
\italic{defaultString} will be displayed to the user as a default answer
to
the question.
It is likely that the default will be displayed as an
initial string. The \italic{defaultString} may be \smaller{NULL} in which
case no default is offered. The \italic{priority} determines whether the
message text shows up in a message line or a dialog box. The
\italic{priority} scale is from 0 to 100, with 100 being the highest
priority. \
\bold{Return value.} In case of error, -1; otherwise a nonnegative
value.
An error usually indicates that the user decided not to answer the
question (i.e. they canceled the question), or that there is already a
question being asked. Most message handlers cannot deal with more than
one
question at once so they return an error when the situation arises. A
error
return should terminate the current user operation in a way that modifies
as little state as possible. \
\begindata{bp,539395656}
Version 2
n 0
\enddata{bp,539395656}
\view{bpv,539395656,1,0,0}
\bold{Example.}
its
square. \
The following example prompts for a number and prints
\programexample{
void PrintSquare(v, key)
struct view *v;
long key;
\{
char buffer[64];
static char lastNumber[64] = "";
if (message_AskForString(v, 0,
"Please enter a number: ", lastNumber,
buffer, sizeof(buffer)) >= 0) \{
long number;
char messageString [256];
if (sscanf(buffer, "%d", &number) != 1)
sprintf(messageString,
"%s is not a valid number.", buffer);
else \{
sprintf(messageString,
"%d squared is %d.", number, number * number);
strcpy(lastNumber, buffer);
\}
message_DisplayString(v, 0, messageString);
\}
\}
}
\
}
\begindata{bp,539396136}
Version 2
n 0
\enddata{bp,539396136}
\view{bpv,539396136,2,0,0}
\paragraph{Asking for a string with completion and help}
\indexi{ \italic{message_AskForStringCompleted}}
\indexi{Message++Command completion}
\indexi{Message++Completion help}
\example{
int message_AskForStringCompleted(v, priority, prompt,
defaultString, buffer, bufferSize, keystate,
completionProc, helpProc, completionData, flag)
struct view *v;
int priority;
char *prompt, *defaultString, *buffer;
int bufferSize;
struct keymap *keystate;
int (*completionProc)(), (*helpProc)();
long completionData, flag;
}
\leftindent{\bold{Class procedure description.} Like
\italic{message_AskForString}, \italic{message_AskForStringCompleted}
asks
the user a question. The first six parameters are identical to
\italic{message_AskForString}. In addition, it provides completion and
help facilities. Completion is a means by which the user can type part of
an answer and have the program provide the rest of it. Finishing off the
end of a unique pathname is an example. The help mechanisms provide a way
for the user to get assistance while the question is being asked. Such
assistance may depend on the context in which it is requested. For
example,
a list of possible completions of the current input could be given. Other
features offered by this function are special key processing and optional
initial string suppression. \
The parameter \italic{keystate} is a keystate, if any, that you wish to
use
to process the user's input. It should be \smaller{NULL} if you want to
use the default processing provided by the message handler. The
parameter
\italic{completionProc} is the name of the procedure that should provide
the rest of the input (i.e., a command completion procedure). The
parameter \italic{helpProc} is the name of a help procedure that the user
can invoke to get help in completing the input. The parameter
\italic{completionData} is any data that you may want to feed into the
\italic{completionProc}; it should be zero if you are not sending any
data.
The flag controls the processing and is formed by a \smaller{OR}-ed
combination of the following values: \
\leftindent{\formatnote{\italic{message_MustMatch}\formatnote{
return valid completions.
\italic{message_InitialHelp}\formatnote{
--
\italic{message_NoInitialString}\formatnote{
initial string.
\italic{message_Mandatory}\formatnote{
answered.
It cannot be punted.
}
}
\bold{Return value.}
value. \
--
--
}Only
}Display help at beginning.
--
}Do not use default as
}The question must be
In case of error, -1, otherwise a nonnegative
\bold{Example.} The following is a call from the class \italic{frame}
that
provides command completion and help for visiting files: \
\example{
msghandler_AskForStringCompleted (messageLine, 0, prompt, defaultName,
bufferName, sizeof(bufferName),NULL, BufferComplete, BufferHelp,
0,message_MustMatch | message_NoInitialString)
}
}\paragraph{Asking a multiple choice question}
\indexi{ \italic{message_MultipleChoiceQuestion}}
\indexi{Message++Multiple choice questions}
\example{
int message_MultipleChoiceQuestion(v, priority, prompt,
defaultChoice, result, choices, abbrevKeys)
struct view *v;
int priority;
char *prompt;
long defaultChoice;
long *result;
char **choices;
char *abbrevKeys;
}
\leftindent{\bold{Class procedure description.}
\italic{message_MultipleChoiceQuestion} sets up a multiple choice
question
for the view \italic{v}, with two or more strings as the choices. As
with
\italic{AskForString}, you must pass a \italic{view}, a
\italic{priority},
and a \italic{prompt} string. \
The parameter \italic{choices} is a \smaller{NULL} terminated array of
strings representing choices. These will be displayed to the user. \
The user's answer is returned in the area pointed to by the parameter
\italic{result}. The \italic{defaultChoice} is what will be returned in
\italic{result} if the user hits the return key. It should correspond to
the entry in the array of choices that you want to be the default. \
The parameter \italic{abbrevKeys} does not seem to be used at this time.
It can be \smaller{NULL}. \
\bold{Return value.}
value. \
In case of error, -1, otherwise a nonnegative
\bold{Example.} The following is how illustrates how you might prompt a
user about unsaved changes. The default choice, 0, is "Yes," to save
them. \
\example{
static char *yesOrNo[] = \{"Yes", "No", NULL\};
msghandler_MultipleChoiceQuestion (messageLine, 0,
"You have unsaved changes;
do you want to save them?",
0, &answer, yesOrNo, NULL)
}
}
\begindata{bp,539404184}
Version 2
n 0
\enddata{bp,539404184}
\view{bpv,539404184,3,0,0}
\paragraph{Canceling the question} \indexi{
\italic{message_CancelQuestion}}
\indexi{Message++Canceling a question}
\example{void message_CancelQuestion(view)
struct view *view;} \
\leftindent{\bold{Class procedure description.
} \italic{message_CancelQuestion} retracts the question. \
\bold{Usage.}
argument.} \
This procedure will not work with a \smaller{NULL} view
\section{Auxiliary Methods}
\paragraph{Positioning a message and controlling the blocking of input}
\indexi{Message++Positioning a message}
\indexi{ \italic{message_Advice}}
\indexi{Message++Blocking user input}
\example{void message_Advice(view, advice);
struct view *view;
enum message_Preference advice;
}
\leftindent{\bold{Class procedure description.} message_Advice is used
to
modify the way certain message functions behave. Notably, it can be used
to
position dialog boxes and to control whether or not questions block. Here
are the possible values of advice with explanations: \
\leftindent{message_NoBlock
\leftindent{If the questions should be non-blocking, that is, the user
should be able to carry out other actions while waiting to answer the
question, then this option is useful, since the user must be able to look
at data in order to figure out the answer to a question. On the other
hand,
the user can change the state of the program while the question is being
asked, therefore the code that is asking the question must be robust
against state chages. \
} \
message_OnTop
message_OnBottom
message_Center
\leftindent{
These options are used to roughly place a dialog box (or other positional
abstraction). The values indicate that the message should be as high up
in
the view as possible, centered in the view, or as low as possible. \
}
}
\bold{Usage.}
argument. \
This procedure will not work with a \smaller{NULL} view
}
\begindata{bp,539407672}
Version 2
n 0
\enddata{bp,539407672}
\view{bpv,539407672,4,0,0}
\paragraph{Getting the current input string}
\indexi{ \italic{message_GetCurrentString}}
\indexi{Message++Getting current input string}
\example{int message_GetCurrentString(view, buffer, bufferSize)
struct view *view;
char *buffer;
int bufferSize;} \
\leftindent{\bold{Class procedure description.}
\italic{message_GetCurrentString} gets the current input string. \
\bold{Return value.} In case of error, -1 will be returned, otherwise a
nonnegative value will be returned. \
\bold{Usage.} Applicable only during calls to \italic{AskForString}
and\italic{ AskForStringCompleted}. This procedure will not work with a
\smaller{NULL} view argument. \
}
\paragraph{Inserting characters} \indexi{
\italic{message_InsertCharacters}}
\indexi{Message++Inserting characters}
\example{int message_InsertCharacters(view, pos, string, len)
struct view *view;
int pos;
char *string;
int len;} \
\leftindent{\bold{Class procedure description.}
\italic{message_InsertCharacters} inserts a \italic{string} of length
\italic{len} at the position \italic{pos} into the input string. \
\bold{Return value.} In case of error, -1 will be returned, otherwise a
nonnegative value will be returned. \
\bold{Usage.}
Applicable only during calls to \italic{AskForString}
and\italic{ AskForStringCompleted}. This procedure will not work with a
\smaller{NULL} view argument. \
}\
\begindata{bp,539412088}
Version 2
n 0
\enddata{bp,539412088}
\view{bpv,539412088,5,0,0}
\paragraph{Deleting characters} \indexi{
\italic{message_DeleteCharacters}}
\indexi{Message++Deleting characters}
\example{int message_DeleteCharacters(view, pos, len)
struct view *view;
int pos, len;} \
\leftindent{
\bold{Class procedure description.} \italic{message_DeleteCharacters}
deletes characters from an input string. \
\bold{Return value.} In case of error, -1 will be returned, otherwise a
nonnegative value will be returned. \
\bold{Usage.} Applicable only during calls to \italic{AskForString}
and\italic{ AskForStringCompleted}. This procedure will not work with a
\smaller{NULL} view argument. \
}
\paragraph{Getting the cursor position}
\indexi{ \italic{message_GetCursorPos}}
\indexi{Message++Getting cursor position}
\example{int message_GetCursorPos(view)
struct view *view;} \
\leftindent{\bold{Class procedure description.}
\italic{message_GetCursorPos} gets the current cursor position in the
input string. \
\bold{Return value.} Returns -1 if procedure was not completed;
otherwise
it returns the position of the cursor in the message line. \
\bold{Usage.} Applicable only during calls to \italic{AskForString}
and\italic{ AskForStringCompleted}. This procedure can be called to find
out where the user is typing. This procedure will not work with a NULL
view
argument. \
}
\paragraph{Setting the cursor position}
\indexi{ \italic{message_SetCursorPos}}
\indexi{Message++Setting cursor position}
\example{int message_SetCursorPos(view, pos)
struct view *view;
int pos;} \
\leftindent{
\bold{Class procedure description.} \italic{message_SetCursorPos} sets
a
cursor position for a message string in the input string. \
\bold{Return value.} In case of error, -1 will be returned, otherwise a
nonnegative value will be returned. \
\bold{Usage.} Applicable only during calls to \italic{AskForString}
and\italic{ AskForStringCompleted}. This procedure will not work with a
\smaller{NULL} view argument. \
}
\begindata{bp,539417416}
Version 2
n 0
\enddata{bp,539417416}
\view{bpv,539417416,6,0,0}
\paragraph{Finding out whether a question is being asked}
\indexi{ \italic{message_Asking}}
\indexi{Message++Avoiding message conflicts}
\example{boolean message_Asking(view)
struct view *view;} \
\leftindent{
\bold{Class procedure description.} \italic{message_Asking} finds out if
a
question is being asked in a view. \
\bold{Return value.} A boolean: \smaller{TRUE} if there is a question
being asked; \smaller{FALSE} otherwise. \
\bold{Usage.} It is sometimes desirable to check if there is a
possibility
that another question is already up when a question is to be asked, so
there would be no conflict between messages. This procedure will not work
with a \smaller{NULL} view argument. \
}
\begindata{bp,539419672}
Version 2
n 0
\enddata{bp,539419672}
\view{bpv,539419672,7,0,0}
Copyright 1992 Carnegie Mellon University and IBM.
All rights reserved.
\smaller{\smaller{$Disclaimer:
Permission to use, copy, modify, and distribute this software and its
documentation for any purpose and without fee is hereby granted, provided
that the above copyright notice appear in all copies and that both that
copyright notice and this permission notice appear in supporting
documentation, and that the name of IBM not be used in advertising or
publicity pertaining to distribution of the software without specific,
written prior permission.
THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD
TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ANY COPYRIGHT
HOLDER BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL
DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
$
}}\enddata{text,538429096}