\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{
default, applications fork.
--
}The application will not fork.
By
\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{
default
is to read.
--
}Do not read an init file.
The
}
\bold{Return value.}
\smaller{FALSE}
upon failure.
A boolean:
\smaller{TRUE} for success;
\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.}
initializes
the foreground and background colors.
\bold{Return value.}
\smaller{FALSE}
upon failure.
A boolean:
\italic{application_Start}
\smaller{TRUE} for success;
\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.
to
override it unless that assumption is not met.
You probably do not need
}
\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.}
\bold{Usage.}
0 for success; -1 for failure.
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}.
appear
in the window's title bar.
\bold{Usage.}
The \italic{name} will
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.}
gets
the name of the application.
\bold{Usage.}
\italic{application_GetName}
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.
that it
is loaded upon use.
\bold{Usage.}
The default is
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 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,539024040}