\begindata{text,539024040}
\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{itemize
}
\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]}
\chapter{Application}\indexi{Application}
The class \italic{application} provides a set of facilities that allow you to create an application program. It provides the methods you need to communicate with \italic{runapp} (run application), an Andrew Toolkit class that runs applications in a way that saves on virtual memory by allowing applications to share code. For example, if a user is running \bold{ez} as well as one of your applications, and your application uses the
\italic{text/textview} pair, your application will share that code with
\bold{ez}, which also uses it. To use the \italic{runapp} and
\italic{application} facilities, you must set up your program so that it uses the methods provided by \italic{application}.
\section{Quick reference list for}\chapter{\section{
}}\section{\section{A}pplication}
\fixedtext{void \bold{application_}DeleteArgs }\fixedindent{(char
**\paramname{argv}, int \paramname{num});}

\fixedtext{void \bold{application_}FinalizeObject }\fixedindent{(struct app
*\paramname{self});}
\fixedtext{boolean \bold{application_}Fork }\fixedindent{(struct application
*\paramname{application});}
\fixedtext{char *\bold{application_}GetATKVersion }\fixedindent{();}
\fixedtext{\bold{application_}GetErrorProc }\fixedindent{(struct application
*\paramname{application});}
\fixedtext{\bold{application_}GetErrorRock }\fixedindent{(struct application
*\paramname{application});}
\fixedtext{\bold{application_}GetForceLoad }\fixedindent{(struct application
*\paramname{application});}
\fixedtext{\bold{application_}GetFork }\fixedindent{(struct application
*\paramname{application});}
\fixedtext{\bold{application_}GetMajorVersion }\fixedindent{(struct application *\paramname{application});}
\fixedtext{\bold{application_}GetMinorVersion }\fixedindent{(struct application *\paramname{application});}
\fixedtext{\bold{application_}GetName }\fixedindent{(struct application
*\paramname{application});}
\fixedtext{\bold{application_}GetPrintVersionFlag }\fixedindent{(struct application *\paramname{application});}
\fixedtext{boolean \bold{application_}InitializeObject
}\fixedindent{(struct app *\paramname{self});}
\fixedtext{boolean \bold{application_}ParseArgs }\fixedindent{(struct application *\paramname{application}, int \paramname{argc}, char
**\paramname{argv});}
\fixedtext{void \bold{application_}PrintVersionNumber
}\fixedindent{(struct application *\paramname{application});}
\fixedtext{void \bold{application_}ReadInitFile }\fixedindent{(struct application *\paramname{application});}
\fixedtext{int \bold{application_}Run }\fixedindent{(struct application
*\paramname{application});}
\fixedtext{\bold{application_}SetErrorProc }\fixedindent{(struct application
*\paramname{application}, \paramname{p});}
\fixedtext{\bold{application_}SetErrorRock }\fixedindent{(struct application

*\paramname{application}, \paramname{r});}
\fixedtext{\bold{application_}SetForceLoad }\fixedindent{(struct application
*\paramname{application}, \paramname{f});}
\fixedtext{\bold{application_}SetFork }\fixedindent{(struct application
*\paramname{application}, \paramname{do});}
\fixedtext{\bold{application_}SetMajorVersion }\fixedindent{(struct application *\paramname{application}, \paramname{mv});}
\fixedtext{\bold{application_}SetMinorVersion }\fixedindent{(struct application *\paramname{application}, \paramname{mv});}
\fixedtext{\bold{application_}SetName }\fixedindent{(struct application
*\paramname{application}, \paramname{str});}
\fixedtext{\bold{application_}SetPrintVersionFlag }\fixedindent{(struct application *\paramname{application}, \paramname{TorF});}
\fixedtext{boolean \bold{application_}Start }\fixedindent{(struct application
*\paramname{application});}
\fixedtext{void \bold{application_}Stop }\fixedindent{(struct application
*\paramname{application});}
\section{Overview of Andrew Toolkit applications}
\subsection{Memory management}
To understand why application programs are all run by a single program, it is useful to understand some things about memory management in virtual memory operating systems.
A major component of the Andrew Toolkit system implementation is its object memory. Formally, we can think of a memory as a set of addressable storage locations. When a program runs, the loader loads the code into memory.
As the program runs, the program may also request the allocation/deallocation of memory. In the Andrew Toolkit, dynamic linking and loading allows all applications to be run from a single program, called runapp (run application).
Runapp contains all the basic components of the toolkit. The code for each individual application is dynamically loaded at run time. The scheme allows
Andrew Toolkit applications to share code. Sharing code has the following benefits:

\itemize{ overall reduction in the amount of paging fewer page faults for frequently used portions of the Andrew Toolkit use of less virtual memory fewer files to fetch when running under a distributed file system reduced file size of applications
}
Thus, you will usually want to build your Andrew Toolkit applications using the facilities provided by the class \italic{application}.
\subsection{Flow of control for running applications}
When\italic{ runapp} loads an application, it asks the application to parse its arguments, if any. For example, the user might invoke
\italic{hwapp} with the command line argument, \italic{-s}:
\example{ runapp -d hwapp -s
}
Then it asks the program to read any initialization files (e.g., a user preference file). Next it asks the application to "start," that is, to create a window, to create any objects within the window, and so forth.
Finally,
\italic{runapp} tells the application to run, that is, to enter the keyboard processing loop. Most application programs start up by creating a set of views and asking the \italic{Interaction Manager} to make one of the views the input focus. See Example 1, Vol. I for more detail.
\subsection{Version Numbers}
The application class contains macro-methods for setting and getting the major and minor version numbers of an application.
SetMajorVersion(mv)
GetMajorVersion()

SetMinorVersion(mv)
GetMinorVersion()
By default, a version message will be printed for the user (i.e. sent to standard error) when an application is started up. To prevent this message from being displayed, the application programmer can call
application_SetPrintVersionFlag(self,FALSE)
This macro-method, like the methods for setting the version number,
\bold{must} be called from the application's \typewriter{InitializeObject
}procedure, since the version number is normally printed before errors from parsing the arguments. Application's that wish to optionally print the version message should start by setting the PrintVersionFlag to FALSE, as above.
They can later chose to print the version message by calling the method,
application_PrintVersionNumber(self).
\subsection{Methods and Class Procedures}
\paragraph{Creating an instance of an application}
\indexi{ \italic{application_New}}
\indexi{Application++Creating}
\example{struct application *application_New ()
}\leftindent{
\bold{Class procedure description. }\italic{application_New} creates a application by dynamically allocating memory for an application structure. In addition, it initializes the newly allocated application structure
\bold{Usage.} You should not need to call \italic{application_New} directly.
The class \italic{runapp} will create an instance.
}
\paragraph{Parsing the command-line arguments}
\indexi{ \italic{application_ParseArgs}}
\indexi{Application++Parsing arguments}
\indexi{Command line arguments}\example{boolean application_ParseArgs
(app, argc, argv) struct application *app; int argc;

char **argv;
}
\leftindent{\bold{Method description.} If the application program name is not set, \italic{application_ParseArgs} sets it. Then it parses arguments.
The following are the flags that it understands and their meaning:
\description{
\italic{\bold{-}d}\formatnote{ -- }The application will not fork. By default, applications fork.
\italic{\bold{-}fg}\formatnote{ -- }Sets the foreground color to the specified string value. The default is \smaller{NULL}.
\italic{\bold{-}bg}\formatnote{ -- }Sets the background color to the specified string value. The default is \smaller{NULL}.
\italic{\bold{-}fl}\formatnote{ -- }Force the loading of the module upon read rather than upon use. The default is to load upon use.
\italic{\bold{-}ni}\formatnote{ -- }Do not read an init file. The default is to read.
}
\bold{Return value.} A boolean: \smaller{TRUE} for success;
\smaller{FALSE} upon failure.
\bold{Side effects.} \italic{super_ParseArgs} changes the \italic{argv} pointer; \italic{argc}, which is passed by value, is unchanged, so it will be inconsistent.
\bold{Usage.} Command-line arguments are parameters, if any, that are passed to a program when it begins running. When an Andrew Toolkit application begins to run, \italic{runapp} calls its \italic{ParseArgs} method. it is called with two arguments. The first, \italic{argc}, is the number of command-line arguments; the second, \italic{argv}, is a pointer to an array of character strings that contain the arguments, one argument per string.
If you are creating an application named \italic{xapp}, and you want to parse command line arguments, you should override \italic{application_ParseArgs}. The method you create should first call \italic{super_ParseArgs}. Next, it should parse its command line arguments using the vector \italic{argv} rather than

\italic{argc} as the loop control.
\begindata{bp,538929224}
\enddata{bp,538929224}
\view{bpv,538929224,1337,0,0}
\bold{Example.} The following shows a typical setup for an application that parses its arguments. The switches, 'c' and 'm' are arbitrary.
\programexample{ boolean xapp__ParseArgs (x, argc, argv) struct xapp *x; int argc; char **argv;
\{
if (!super_ParseArgs (x, argc, argv))
return FALSE; while (*++argv != NULL && **argv == '-')
switch ((*argv [1])\{
case 'c':
/* do an appropriate action */
break;
case 'm':
/* do an appropriate action */
default:
fprintf (stderr,"%s: unrecognized switch: %s\\n",
xapp_GetName(x), *argv);
return FALSE;
\}
if (*argv != NULL)
x->args=argv;
return TRUE;
\}
}

}
\begindata{bp,538928456}
\enddata{bp,538928456}
\view{bpv,538928456,1338,0,0}
\paragraph{Reading the initialization file}
\indexi{ \italic{application_ReadInitFile}}
\indexi{Application++Initialization file}
\indexi{Initialization file}\example{void application_ReadInitFile (app) struct application *app;
}
\leftindent{\bold{Method description.} If there is an initialization file,
\italic{\bold{.}<x>init}, for the application in the home directory,
\italic{application_ReadInitFile} attempts to load (cf.,
\italic{init_Load}) only that (e.g., \bold{x}ezinit); if not, it looks for a global init and tries to load it (e.g., /usr/local/lib/global.ezinit).
}
\paragraph{Starting the application} \indexi{ \italic{application_Start}}
\indexi{Application++Starting}
\example{boolean application_Start (self) struct application *self;
}
\leftindent{\bold{Method description.} \italic{application_Start} initializes the foreground and background colors.
\bold{Return value.} A boolean: \smaller{TRUE} for success;
\smaller{FALSE} upon failure.
\bold{Usage.} If you are creating an application, you should override this method. See Example 1, Vol. I for a detailed discussion of its use.
}
\paragraph{Running the application} \indexi{ \italic{application_Run}}
\indexi{Application++Running}
\example{int application_Run (self) struct application *self;

}
\leftindent{\bold{Method description.} \italic{application_Run} enters the
\italic{im} interaction loop by calling the
\italic{im_KeyboardProcessor}.
}
\bold{Return value.} 0 for success; -1 for failure.
\bold{Usage.} This method assumes interaction. You probably do not need to override it unless that assumption is not met.
\paragraph{Forking an application} \indexi{Application++Forking}
\indexi{ \italic{application_Fork}}
\indexi{Fork}\example{boolean application_Fork (self) struct application *self;
}
\leftindent{\bold{Method description.} \italic{application_Fork} forks the application, provided that the fork flag has not been set to
\smaller{FALSE}.
\bold{Return value.} 0 for success; -1 for failure.
\bold{Usage.} Used by \italic{application_Run}.
}
\paragraph{Deleting arguments} \indexi{Application++Deleting arguments}
\indexi{ \italic{application_DeleteArgs}}
\example{void application_DeleteArgs (argv, n) char **argv; int n;
}
\leftindent{\bold{Class procedure description.}
\italic{application_DeleteArgs} deletes \italic{n} arguments from
\italic{argv}.
}
\paragraph{Controlling whether the application forks}

\indexi{Application++Forking}
\indexi{ \italic{application_SetFork}}
\example{application_SetFork (app, value) struct application *app; boolean value;
}
\leftindent{\bold{Macromethod description.}
\italic{application_SetFork} sets the fork flag to value. If \smaller{TRUE}, the application will fork; if
\smaller{FALSE}, it will not.
\bold{Side effects.} Affects \italic{application_Run} and
\italic{application_Fork}.
\bold{Usage.} Arguments to macro methods should not have side effects.
}
\paragraph{Finding out whether the application will fork}
\indexi{Application++Forking}
\indexi{ \italic{application_GetFork}}
\example{boolean application_GetFork (app) struct application *app;
}
\leftindent{\bold{Macromethod description.}
\italic{application_GetFork} returns \smaller{TRUE} if the application will fork; \smaller{FALSE} otherwise.
\bold{Usage.} Arguments to macro methods should not have side effects.
}
\paragraph{Setting the application's name} \indexi{Application++Name}
\indexi{ \italic{application_SetName}}
\example{application_SetName (app, name) struct application *app. char *name;
}
\leftindent{\bold{Macromethod description.}
\italic{application_SetName}

sets the application's name to \italic{name}. The \italic{name} will appear in the window's title bar.
\bold{Usage.} Arguments to macro methods should not have side effects.
}
\paragraph{Finding out an application's name} \indexi{Application++Name}
\indexi{ \italic{application_GetName}}
\example{char *application_GetName (app) struct application *app;
}
\leftindent{\bold{Macromethod description.} \italic{application_GetName} gets the name of the application.
\bold{Usage.} Arguments to macro methods should not have side effects.
}
\paragraph{Forcing the application to be loaded}
\indexi{Application++Loading}
\indexi{ \italic{application_SetForceLoad}}
\example{application_SetForceLoad (app, val) struct application *app; boolean val;
}
\leftindent{\bold{Macromethod description.}
\italic{application_SetForceLoad} sets a flag that forces the application to be loaded. The default is that it is loaded upon use.
\bold{Usage.} Arguments to macro methods should not have side effects.
}
\paragraph{Finding out the load status of an application}
\indexi{Application++Loading}
\indexi{ \italic{application_GetForceLoad}}
\example{boolean application_GetForceLoad (app)

struct application *app;
}
\leftindent{\bold{Macromethod description.}
\italic{application_GetForceLoad} returns \smaller{TRUE} if the application will be loaded upon reading;
\smaller{FALSE} is it will be loaded upon use.
\bold{Usage.} Arguments to macro methods should not have side effects.
}
\formatnote{
\paragraph{Set an error procedure}
\example{SetErrorProc(p) ((self)->errorProc=(p))
}\leftindent{
\bold{Macromethod description.}
\bold{Side effects.}
\bold{Usage.}
\bold{Example.}
}
\paragraph{Get an error procedure}
\example{GetErrorProc() ((self)->errorProc)
}
\leftindent{\bold{Macromethod description.}
\bold{Side effects.}
\bold{Usage.}
\bold{Example.}
}
\paragraph{Set an error rock}

\example{SetErrorRock(r) ((self)->errorRock=(r))
}
\leftindent{\bold{Macromethod description.}
\bold{Side effects.}
}
\bold{Usage.}
\bold{Example.}
\paragraph{Get an error rock}
\example{GetErrorRock() ((self)->errorRock)
}
\leftindent{\bold{Macromethod description.}
\bold{Side effects.}
\bold{Usage.}
\bold{Example.}
}
}\leftindent{
}
\begindata{bp,537558784}
\enddata{bp,537558784}
\view{bpv,537558784,1340,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 is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice, this permission notice, and the following disclaimer appear in supporting documentation, and that the names of
IBM, Carnegie Mellon University, and other copyright holders, not be used in advertising or publicity pertaining to distribution of the software

without specific, written prior permission.
IBM, CARNEGIE MELLON UNIVERSITY, AND THE OTHER COPYRIGHT HOLDERS
DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING
ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT
SHALL IBM, CARNEGIE MELLON UNIVERSITY, OR ANY OTHER 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,539024040}