ATARILIB(3A) ATARILIB(3A)
NAME
AtariLibInit - Atari Application Library
SYNOPSIS
#include <X11/Intrinsic.h>
AtariLibInit (w)
widget w;
#include <Atari/AtariLib.h>
#include <Atari/libgls.h>
DESCRIPTION
AtariLibInit initializes the Atari Application Library. It
should be called immediately after FmInitialize (3A), with
the widget w being the widget returned from FmInitialize.
Initializing the Atari library does the following things:
o A log file is opened using LogOpen(3A). Its name is
the name of the widget passed to AtariLibInit.
Normally, this is the same as the program name passed
to FmInitialize.
o The environment variable NLSPATH is expanded using
AddPathV(3A) to include the directory containing the
catalog files for the Atari Application Library.
o The generic Atari Application Library catalog file is
opened, followed by the catalog file whose name is the
name of the widget
o The character set used by XmStringCreateSimple(3X) is
obtained by calling GetSimpleCharSet(3A).
o Functions used by library routines, or useful to the
application program in XFaceMaker scripts, are
attached.
Page 1 (printed 9/3/91)
ATARILIB(3A) ATARILIB(3A)
In addition, some convenient global variables are set:
Widget toplevel
The top-level widget. This is the widget w passed
to AtariLibInit , useful for some X Toolkit calls.
Display *display
The default display, useful for some X Toolkit
calls.
Screen *screen
The default screen, useful for some X Toolkit
calls.
XtAppContext appcontext
The current application context, useful for some X
Toolkit calls.
int screenno
The default screen number useful for some X
library calls.
Window rootwindow
The root window useful for some X library calls.
int rootwidth
The width of the root window, useful for some X
library calls.
int rootheight
The height of the root window, useful for some X
library calls.
FUNCTIONS
Here is a list of functions in the library, divided into
logical groups.
Help Sub-System
HelpInit Initialize help sub-system.
Page 2 (printed 9/3/91)
ATARILIB(3A) ATARILIB(3A)
PopupHelpAndWait Present help box and wait for
response.
Alert Sub-System
AlertInit Initialize alert box sub-system.
InternalError Present an internal error, then
exit.
AlertSetButtons Set buttons in an alert box.
AlertHelp Present help box for an alert box.
PopupAlertAndWait Present alert box and wait for a
response. There are also
convenience routines to present a
standard type dialog box and wait
for a response:
PopupErrorAndWait
PopupInformationAndWait
PopupMessageAndWait
PopupQuestionAndWait
PopupWarningAndWait
PopupWorkingAndWait
Interactive Command Execution Sub-System
ExecuteAttachFunctions Attach XFaceMaker 2 functions for
interactive command execution sub-
system.
ExecuteInit Initialize interactive command
execution sub-system.
ExecuteSetMessages Set messages for interactive
command execution session.
ExecuteDoneCallback Arrange callback when interactive
command execution session has
completed.
Page 3 (printed 9/3/91)
ATARILIB(3A) ATARILIB(3A)
ExecuteList Execute a command and a list of
arguments.
ExecuteListV Execute a command and a vector of
arguments.
ExecuteString Use the shell to execute a command
in a string.
Non-Interactive Command Execution Sub-System
RunProcess Run a process with I/O redirection.
RunProcessV Run a process with command
arguments as a vector.
AddChildHandler Add a child handler to a running
process.
GetCommandStatus Run a process and call a function
with its exit status.
GetCommandStatusV Same as above, with command
arguments as a vector.
High-level Asynchronous Input/Output Routines
ReadFileData Read raw data from a file.
ReadFileLines Read lines from a file.
ReadFileStrings Read lines from a file and store in
an array of strings.
ReadPipeData Read raw data from a pipe.
ReadPipeDataV Like ReadPipeData, with a command
argument vector.
ReadPipeLines Read lines from a pipe.
ReadPipeLinesV Like ReadPipeLines, with a command
Page 4 (printed 9/3/91)
ATARILIB(3A) ATARILIB(3A)
argument vector.
ReadPipeStrings Read lines from a pipe and store in
an array of strings.
ReadPipeStringsV Like ReadPipeStrings, with a
command argument vector.
WriteFileData Write raw data from a file.
WriteFileLines Write lines from a file.
WritePipeData Write raw data from a pipe.
WritePipeDataV Like WritePipeData, with a command
argument vector.
WritePipeLines Write lines from a pipe.
WritePipeLinesV Like WritePipeLines, with a command
argument vector.
Low-level Asynchronous Input/Output Routines
AddIoProc Register an asynchronous I/O
procedure.
RemoveIoProc Remove an asynchronous I/O
procedure.
OpenReadPipe Open a pipe for reading.
OpenReadPipeV Open a read pipe, with command
arguments as a vector
OpenWritePipe Open a pipe for writing.
OpenWritePipeV Open a write pipe, with command
arguments as a vector.
OpenFilter Run a filter process with pipes
Page 5 (printed 9/3/91)
ATARILIB(3A) ATARILIB(3A)
both in and out.
OpenFilterV Run a filter, with command
arguments as a vector.
GetPipePid Get process ID of a pipe from its
file descriptor.
ClosePipe Close pipe file descriptor.
Application Logging Routines
LogOpen Open a log file.
LogWrite Write to a log file.
LogDebug Put debug message in log file.
LogAssert Check an assertion and report
failure in log file.
LogSystemError Report a system error to the log
file.
LogClose Close and remove a log file.
LogReopen Change a log file.
Miscellaneous Routines
AddPath Add an element to a path-like
environment variable.
AddPathV Add a vector of elements to a path
variable.
AdjustWmPadding Adjust padding values depending on
resource values.
FindWmPadding Find out size of window manager
decorations.
Page 6 (printed 9/3/91)
ATARILIB(3A) ATARILIB(3A)
FmCatGetSAlloc Call FmCatGetS and copy the result
in a dynamic buffer.
FmCatGetSRealloc Call FmCatGetS and re-use given
buffer.
GetSimpleCharSet Get default character set for
OSF/Motif strings.
PositionBeneath Position a widget beneath another
widget.
PositionCenter Position a widget centered over
another widget.
PositionNear Position a widget near another
widget.
PositionOver Position a widget over another
widget.
PositionRootCenter Position a widget in the center of
the root window.
INTERNATIONALIZATION
The include file <Atari/AtariLib.h> defines these macros for
internationalization of applications:
OK_RETURN The string returned when the OK
button is pressed in an alert box.
See PopupAlertAndWait(3A).
CANCEL_RETURN The string returned when the Cancel
button is pressed in an alert box.
See PopupAlertAndWait(3A).
The include file <Atari/libgls.h> defines these
international message catalog sets and message numbers used
by the Atari library.
Page 7 (printed 9/3/91)
ATARILIB(3A) ATARILIB(3A)
Message Catalog Sets
BUTTON_SET 250 Standard button labels are defined
in this set.
MESSAGE_SET 251 Library messages are defined in
this set.
TITLE_SET 252 Library titles are defined in this
set.
ALERT_SET 253 All alert box text messages are
defined in this set.
Application-specific messages begin
at ALERT_APPLICATION.
HELP_TITLE_SET 254 Help message titles are defined in
this set.
HELP_TEXT_SET 255 Help message text messages are
defined in this set. The first
message in a group of help message
has the same message number as its
title in the set HELP_TITLE_SET.
Alert Set 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
Page 8 (printed 9/3/91)
ATARILIB(3A) ATARILIB(3A)
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 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.
Button Set Message Numbers
Name Number American Value
YES_BUTTON_MSG 1 Yes
NO_BUTTON_MSG 2 No
OK_BUTTON_MSG 3 OK
APPLY_BUTTON_MSG 4 Apply
RETRY_BUTTON_MSG 5 Retry
STOP_BUTTON_MSG 6 Stop
RESET_BUTTON_MSG 7 Reset
CANCEL_BUTTON_MSG 8 Cancel
HELPDOTS_BUTTON_MSG 9 Help ...
ABORT_BUTTON_MSG 10 Abort
NEXT_BUTTON_MSG 11 Next
PREVIOUS_BUTTON_MSG 12 Previous
START_BUTTON_MSG 13 Start
RESTORE_BUTTON_MSG 14 Restore
FILE_BUTTON_MSG 20 File
Page 9 (printed 9/3/91)
ATARILIB(3A) ATARILIB(3A)
NEW_BUTTON_MSG 21 New
OPEN_BUTTON_MSG 22 Open ...
READ_BUTTON_MSG 23 Read ...
PRINT_BUTTON_MSG 24 Print
PRINTDOTS_BUTTON_MSG 25 Print ...
SAVE_BUTTON_MSG 26 Save
SAVE_AS_BUTTON_MSG 27 Save As ...
CLOSE_BUTTON_MSG 28 Close
EXIT_BUTTON_MSG 29 Exit
EDIT_BUTTON_MSG 30 Edit ...
UNDO_BUTTON_MSG 31 Undo
CUT_BUTTON_MSG 32 Cut
COPY_BUTTON_MSG 33 Copy
PASTE_BUTTON_MSG 34 Paste
CLEAR_BUTTON_MSG 35 Clear
DELETE_BUTTON_MSG 36 Delete
VIEW_BUTTON_MSG 40 View
OPTIONS_BUTTON_MSG 50 Options
SEE_OPTIONS_BUTTON_MSG 51 See Options
PROPERTIES_BUTTON_MSG 60 Properties
HELP_BUTTON_MSG 90 Help
ON_CONTEXT_BUTTON_MSG 91 On Context
ON_HELP_BUTTON_MSG 92 On Help ...
ON_WINDOW_BUTTON_MSG 93 On Window ...
ON_KEYS_BUTTON_MSG 94 On Keys ...
ON_MOUSE_BUTTON_MSG 95 On Mouse ...
INDEX_BUTTON_MSG 96 Index ...
TUTORIAL_BUTTON_MSG 97 Tutorial ...
ON_VERSION_BUTTON_MSG 99 On Version ...
FILE_MNEMONIC 120 F
NEW_MNEMONIC 121 N
OPEN_MNEMONIC 122 O
READ_MNEMONIC 123 R
PRINT_MNEMONIC 124 P
Page 10 (printed 9/3/91)
ATARILIB(3A) ATARILIB(3A)
SAVE_MNEMONIC 126 S
SAVE_AS_MNEMONIC 127 A
CLOSE_MNEMONIC 128 C
EXIT_MNEMONIC 129 E
EDIT_MNEMONIC 130 E
UNDO_MNEMONIC 131 U
CUT_MNEMONIC 132 t
COPY_MNEMONIC 133 C
PASTE_MNEMONIC 134 P
CLEAR_MNEMONIC 135 e
DELETE_MNEMONIC 136 D
VIEW_MNEMONIC 140 V
OPTIONS_MNEMONIC 150 O
SEE_OPTIONS_MNEMONIC 151 S
PROPERTIES_MNEMONIC 160 P
HELP_MNEMONIC 190 H
ON_CONTEXT_MNEMONIC 191 C
ON_HELP_MNEMONIC 192 H
ON_WINDOW_MNEMONIC 193 W
ON_KEYS_MNEMONIC 194 K
ON_MOUSE_MNEMONIC 195 M
INDEX_MNEMONIC 196 I
TUTORIAL_MNEMONIC 197 T
ON_VERSION_MNEMONIC 199 V
SEE ALSO
xfm(1A), catopen(3A), XmStringCreateSimple(3X),
AddPathV(3A), FmCatOpen(3A), GetSimpleCharSet(3A),
LogOpen(3A), PopupAlertAndWait(3A), XmStringCreateSimple(3X)
Page 11 (printed 9/3/91)