ALERTINIT(3A) ALERTINIT(3A)
NAME
AlertInit, AlertSetButtons, PopupAlertAndWait,
PopupErrorAndWait, PopupInformationAndWait,
PopupMessageAndWait, PopupQuestionAndWait,
PopupWarningAndWait, PopupWorkingAndWait, InternalError -
standard Atari alert box presentation for OSF/Motif
SYNOPSIS
#include <Xm/Xm.h>
int AlertInit (name)
char *name;
AlertSetButtons (ok, cancel, help, def)
int ok;
int cancel;
int help;
int def;
char *PopupAlertAndWait (w, type, msg, arg ...)
Widget w;
int type;
int msg;
char *PopupErrorAndWait (w, msg, arg ...)
Widget w;
int msg;
char *PopupInformationAndWait (w, msg, arg ...)
Widget w;
int msg;
char *PopupMessageAndWait (w, msg, arg ...)
Widget w;
int msg;
char *PopupQuestionAndWait (w, msg, arg ...)
Widget w;
int msg;
Page 1 (printed 9/3/91)
ALERTINIT(3A) ALERTINIT(3A)
char *PopupWarningAndWait (w, msg, arg ...)
Widget w;
int msg;
char *PopupWorkingAndWait (w, msg, arg ...)
Widget w;
int msg;
InternalError (w, msg, arg ...)
Widget w;
int msg;
DESCRIPTION
AlertInit initializes the alert routines. This should be
called after loading the first application shell and
initializing the atari help routines (see HelpInit(3A)).
The name is used with the alert box type in the title bar of
the alert box. It must be available for access, even
through subsequent FmCatGetS calls. It will not be modified
by the alert routines. This returns zero on success and -1
on failure. The application should exit if -1 is returned.
AlertSetButtons sets the OK, Cancel, and Help label buttons
using the message numbers in ok, cancel, and help,
respectively. If a message number is zero, the button will
be hidden instead. The set BUTTON_SET is used to look up
the labels. This set number and message numbers for
standard labels are defined in <Atari/libgls.h>. The fourth
parameter indicates which button, and is one of
XmDIALOG_NONE, XmDIALOG_CANCEL_BUTTON, XmDIALOG_OK_BUTTON,
or XmDIALOG_HELP_BUTTON as defined in the include file
<Xm/Xm.h>. AlertSetButtons should be called to configure
the buttons in an alert box before actually exposing the
alert box using PopupAlertAndWait. If one of the
convenience routines are used, AlertSetButtons should not be
called. PopupAlertAndWait pops up the alert box whose
buttons were configured by AlertSetButtons. The widget w is
the widget that caused the alert. The alert box will pop up
near this widget, according to the OSF/Motif Style Guide
recommendation. That is, PopupAlertAndWait will try to
Page 2 (printed 9/3/91)
ALERTINIT(3A) ALERTINIT(3A)
place the alert box successively to the right, to the left,
beneath, and above the widget, depending on the space
available on the screen. If the widget w is NULL, the alert
box will pop up in the center of the screen.
The type indicates the type of alert box, and is one of
XmDIALOG_ERROR, XmDIALOG_INFORMATION, XmDIALOG_MESSAGE,
XmDIALOG_QUESTION, XmDIALOG_WARNING, or XmDIALOG_WORKING, as
defined in <Xm/Xm.h>. The msg is the message number of of
the alert text. It belongs to the set ALERT_SET as defined
in <Atari/libgls.h>. There are also some message numbers
for standard alert boxes. The Atari Application library
currently defines these values in <Atari/libgls.h> for alert
message numbers:
ALERT_SORRY (1)
A message for an alert text could not be found.
ALERT_EXIT (2)
A request to exit the application was made without
saving changes. This alert confirms the request.
ALERT_ABORT (3)
A request to abort an execute box was made (see
ExecuteInit(3A)). This alert confirms the
request.
ALERT_BAD_HELP (4)
A widget outside the application was chosen via
Help On Context.
ALERT_INIT_FAIL (5)
An internal error occured and something in the
initialization process failed.
ALERT_EXEC_FAIL (6)
An internal error occured and an attempt to run an
execute box failed.
ALERT_NO_HELP (7)
Page 3 (printed 9/3/91)
ALERTINIT(3A) ALERTINIT(3A)
No help available because either the title or the
text message number could not be found.
ALERT_MEMORY (8)
No more space is available to allocate memory.
ALERT_APPLICATION (100)
All application-defined alert box messages should
start with this value. Alert box messages with
smaller numbers are reserved for the Atari
Application Library.
Standard alert messages can be replaced with messages more
specific to the running application in the application's
catalog file.
If any step in the alert process fails, the program exits
and the user must resort to looking in the log file to see
what happened (see LogOpen(3A)).
The message must contain newlines since the alert text is in
a label.
The message may also contain printf-style directives, and
the arguments to PopupAlertAndWait after msg will be used to
format the string using vsprintf.
The button pressed, either "OK" or "Cancel" (regardless of
the actual label used) is returned.
These are convenience functions for putting up default
message box configurations. These call AlertSetButtons to
set the default button settings and PopupAlertAndWait with
the indicated type. Here are the button labels and settings
used:
Routine Name OK Cancel Help Default
PopupErrorAndWait OK Help ... OK
PopupInformationAndWait OK Help ... OK
Page 4 (printed 9/3/91)
ALERTINIT(3A) ALERTINIT(3A)
PopupMessageAndWait OK Help ... OK
PopupQuestionAndWait Yes No Help ... Yes
PopupWarningAndWait OK Cancel Help ... Cancel
PopupWorkingAndWait Stop Help ... none
They all return the button pushed in the same manner as
PopupAlertAndWait. They also take printf -style arguments
after msg.
InternalError reports an internal error. It pops an error
alert box with only an OK button. When the user confirms
reading the message by pressing the OK button, this function
will exit. The message should inform the user that it will
exit.
XFACEMAKER NOTES
AtariLibInit(3A) attaches the functions AlertSetButtons,
PopupAlertAndWait, PopupErrorAndWait,
PopupInformationAndWait, PopupMessageAndWait,
PopupQuestionAndWait, PopupWarningAndWait,
PopupWorkingAndWait, and InternalError so they may be called
from XFaceMaker scripts.
SEE ALSO
AtariLib(3A), HelpInit(3A), xfm(1A)
Page 5 (printed 9/3/91)