summaryrefslogtreecommitdiff
path: root/macros/latex209/contrib/manpage
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex209/contrib/manpage
Initial commit
Diffstat (limited to 'macros/latex209/contrib/manpage')
-rw-r--r--macros/latex209/contrib/manpage/example1.tex421
-rw-r--r--macros/latex209/contrib/manpage/example2.tex264
-rw-r--r--macros/latex209/contrib/manpage/manpage.sty342
-rw-r--r--macros/latex209/contrib/manpage/sample.tex230
4 files changed, 1257 insertions, 0 deletions
diff --git a/macros/latex209/contrib/manpage/example1.tex b/macros/latex209/contrib/manpage/example1.tex
new file mode 100644
index 0000000000..31466a3ce7
--- /dev/null
+++ b/macros/latex209/contrib/manpage/example1.tex
@@ -0,0 +1,421 @@
+\documentstyle[11pt,twoside,manpage]{report}
+\begin{document}
+
+\begin{manpage}{OIM Library}{Button}{Draft}
+
+\subtitle{Name}
+ Button --- a graphical event object that can be turn-on turn-off
+
+\subtitle{Declaration}
+ \#include \<button.h\>
+
+\function{Button(Point origin, Point corner, const~char\* label,
+ int foreground_color = WHITE,
+ int background_color = BLACK,
+ int frame_style = IN_BORDER,
+ Boolean show_status = SHOW)}
+ Construct a button inside a rectangle area with lower left vertex at
+ "origin" and upper right vertex at "corner". A button is actually a
+ round-cornered box in shape, so the "origin" and "corner" are located
+ outside of the button area. The "label" is for button label. The
+ first highlighted character in the label text will be the hot key when
+ the mouse is disabled, otherwise highlighted text have no effects.
+ For example, label "@N@ext" designate "N" as the hot key for the button
+ if the mouse do not present; "@N@ext" and "Next" are the same when the
+ mouse is enabled. By default, if the mouse driver is loaded before
+ program execution, it is enabled. Other attributes are self-explanatory.
+ Foreground color is also used for label color.
+
+\function{Button(int left, int bottom, int right, int top, const~char\* label,
+ int foreground_color = WHITE,
+ int background_color = BLACK,
+ int frame_style = IN_BORDER,
+ Boolean show_status = SHOW)}
+ Construct a button with "left", "bottom", "right" and "top" as its
+ boundaries. Button will be shown when created by default.
+
+\subtitle{Description}
+ Button is similar to electronic touch buttons in operation. It can be
+ pressed on or pressed off depending on its current status. Usually,
+ we use normal color to indicate for button "off" position and highlight
+ color for button "on" position. Button is an effect way to implement
+ boolean variables that can toggled on a screen. When the mouse is
+ enabled, point the mouse cursor inside the button area to press the
+ button. When the mouse is disabled, a hot key have to be specified
+ and press that key to trigger a button press operation.
+
+\subtitle{Public \\ Operations}
+
+\function{Boolean pressed()}
+ Check if the button has been pressed, usually in a loop. If it is,
+ the switch action (highlight or redraw the button) is performed.
+
+\function{Boolean isOn()}
+ Return TRUE if the button is at "on" (highlighted) position.
+
+\function{Boolean isOff()}
+ Return TRUE if the button is at "off" (normal color) position.
+
+\function{Boolean isHide()}
+ Return TRUE if at least one hide operation is outstanding.
+
+\function{void turnOn()}
+ Highlight the button figure and set the button status to "on".
+
+\function{void turnOff()}
+ Redraw the button figure using the normal color and set the button
+ status to "off".
+
+\function{void show()}
+ Set the hide status to false and draw the button figure in normal
+ or highlight color depending on current button status.
+
+\function{void hide()}
+ Set the hide status to true and erase the button figure by drawing
+ a box that covers the button, the color is taken from a pixel just
+ outside of the button and fill-pattern is SOLID_FILL.
+
+\subtitle{Virtual \\ Operations}
+
+\function{Boolean isSelected(Point p)}
+ This function is used in the event handler. Return TRUE if the hot key
+ is press when mouse is not enabled, when mouse is enabled check if the
+ mouse cursor is pressed and it is inside the button figure.
+
+\function{int status()}
+ Returns 0 if the button is off and 1 if the button is on.
+ This function is called in the event handler if there is a event
+ function bonded to the button (see Event for more details). The
+ value of the function is passed to the event function as default
+ argument value.
+
+\function{int select()}
+ The same as saying turnOn() when the button is off or turnOff() when
+ the button is on. This function is hardly needed. It is here simply
+ because the Event class has it defined and the Button class is a
+ subclass of Event.
+
+\function{void bind(void \hbox{\rm (\*{\it handler})(int)})}
+ Associate a function (often referred as the button handler) with the
+ button. After the function "handler" is bonded to the button, it is
+ invoked automatically every time the button is pressed by the event
+ handler. The argument value to the function is passed as the status
+ of the button. The default action taken by the event handler can be
+ modified by changing the next function action().
+
+\function{void action(int status)}
+ The default action function called through the event handler. It defines
+ the behavior of the button module when a function is bonded to the button.
+ Not to modify this function unless it is absolutely necessary because it
+ redefines the semantics of all button objects.
+
+\subtitle{See Also}
+ Event, Choice, RoundBox
+
+\subtitle{Author}
+ Rong Chen at the Office for Information Management, UIUC. 9-1-89.
+
+\end{manpage}
+\newpage
+\begin{verbatim}
+ /* EXAMPLE 1 */
+ #include <time.h>
+ #include "key.h"
+ #include "button.h"
+
+ main() {
+ Key key;
+ Point a1(100, 100), a2(240, 130);
+ Button a(a1, a2, "@F@irst Button", WHITE, RED);
+ Button b(400, 100, 540, 120, "@S@econd Button", WHITE, BLUE);
+ Point c1(250, 200), c2(400, 300);
+ Button c(c1, c2, "@T@hird Button\nhas\nThree Lines", WHITE, GREEN);
+ while (1) {
+ if (a.pressed()) { /* sleep(1); a.turnOff(); */ }
+ if (b.pressed()) { sleep(1); b.turnOff(); }
+ if (c.pressed()) { break; }
+ }
+ a.hide(); b.hide(); key.waitFor(CR);
+ }
+
+ /* EXAMPLE 2 */
+ #include <stdlib.h>
+ #include "button.h"
+ #include "box.h"
+
+ void funcA(int) {
+ Box infoBox(0, 0, MAX_X, 40, RED, CYAN);
+ infoBox << "A button is pressed";
+ }
+ void funcB(int) {
+ Box infoBox(0, 0, MAX_X, 40, BLUE, CYAN);
+ infoBox << "B button is pressed";
+ }
+ void funcC(int) { exit(0); }
+
+ main() {
+ Button a(100, 100, 240, 130, "Button @A@", WHITE, RED);
+ Button b(400, 100, 540, 120, "Button @B@", WHITE, BLUE);
+ Button c(250, 200, 400, 300, "@E@xit", WHITE, GREEN);
+ a.bind(funcA); b.bind(funcB); c.bind(funcC);
+ Event::waitForEvents();
+ }
+\end{verbatim}
+
+\end{document}
+
+Path: jarthur!usc!julius.cs.uiuc.edu!ux1.cso.uiuc.edu!ux1.cso.uiuc.edu!m.cs.uiuc.edu!rchen
+From: rchen@m.cs.uiuc.edu
+Newsgroups: comp.text.tex
+Subject: latest manpage.sty for C++ library
+Message-ID: <69100010@m.cs.uiuc.edu>
+Date: 15 Sep 90 20:53:00 GMT
+Lines: 510
+Nf-ID: #N:m.cs.uiuc.edu:69100010:000:19265
+Nf-From: m.cs.uiuc.edu!rchen Sep 15 15:53:00 1990
+
+
+% MANPAGE DOCUMENT STYLE -- Created 25 May 1990, Updated 15 September 1990
+% manpage.sty
+
+% Rong Chen (rchen@cs.uiuc.edu)
+% Department of Computer Science
+% University of Illinois at Urbana-Champaign
+% Urbana, IL 61801
+
+% Copyright (c) 1990 by Rong Chen
+% Permission to copy all or part of this work is granted, provided
+% that the copies are not made or distributed for resale, and that
+% the copyright notice and this notice are retained.
+%
+% THIS WORK IS PROVIDED ON AN "AS IS" BASIS. THE AUTHOR PROVIDES NO
+% WARRANTY WHATSOEVER, EITHER EXPRESS OR IMPLIED, REGARDING THE WORK,
+% INCLUDING WARRANTIES WITH RESPECT TO ITS MERCHANTABILITY OR FITNESS
+% FOR ANY PARTICULAR PURPOSE.
+
+% This style option is designed to work with the report document style
+% of LaTeX version 2.09. Use \documentstyle[11pt,manpage]{report}
+%
+% The commands that are created in the style file are:
+%
+% \begin{manpage}{Title}{Module}{Version} % see an example, all will be clear
+% \end{manpage} % end of manpage environment
+% \function{#1} (e.g., \function{void demo(int dummy)}) % with \medskip added
+% \function*{#1} (e.g., \function*{void demo(int dummy)})% no extra spacing
+% \subtitle{#1} (e.g., \subtitle{ANTHOR}) % fit in the same line if possible
+% \subtitle*{#1} (e.g., \subtitle*{AUTHOR})% always break a newline
+% "#1" (e.g., "dummy_variable") % argument is in italic&unbreakable
+% \separator % draw a thin line to seperate suntitle from the text
+% \header{#1}{#2}{#3} % in case you want to have a header and
+% \footer{#1}{#2}{#3} % a footer outside of the manpage environment
+% \dq % print double quote character (")
+%
+% In the \function macro, data types and their dummy arguments are separated
+% by a space. So if you have a function like "int f(const int n)", you should
+% document it as \function{int f(const~int n)}. The argument n is optional.
+% In the \subtitle macro, two lines of text may be devided by "\\".
+%
+% The following characters (control-sequents) are defined (or redefined) as:
+%
+% \* --- the same as $\ast$
+% \< --- the same as $\langle$
+% \> --- the same as $\rangle$
+% < --- the same as $<$
+% > --- the same as $>$
+% _ --- the same as \_
+% + --- the same as $+$
+% | --- the same as $\mid$
+% ^ --- hat character that is defined as $\wedge$ being raised 0.6ex
+% " --- the same as {\tt "} when outside of the manpage environment,
+% otherwise use \dq instead
+
+% If you make any improvements, I'd like to hear about them.
+
+\headheight 24pt % See LaTeX book for definitions
+\headsep 12pt
+\textwidth 6.25in
+\textheight 8.0in
+\topmargin 0in
+\marginparwidth 0pt
+\oddsidemargin 0pt
+\evensidemargin 0pt
+\marginparsep 0pt
+\parindent 0pt
+\newdimen\argindent \argindent 3em % indentation for function arguments
+\parskip 10pt plus 1pt
+
+\newcommand{\header}[3]{\gdef\@header{{#1}{#2}{#3}}}
+\newcommand{\footer}[3]{\gdef\@footer{{#1}{#2}{#3}}}
+
+\catcode`\"=\active
+\def\arg@quote#1"{\hbox{\it #1\/}}
+\def\tt@quote{\hbox{\tt \char`\" \relax}}
+\let"=\tt@quote
+\let\dq=\tt@quote
+
+\def\separator{\rule{\linewidth}{0.5pt}}
+
+\def\function{\@ifstar{\@func@star}{\@func@norm}}
+\def\@func@star#1{\expandafter\@function#1 \\ }
+\def\@func@norm#1{\expandafter\@function#1 \medskip\\ }
+
+\newdimen\arg@dim % temp variables that you don't want to know
+\newdimen\line@siz
+\newbox\arg@box
+
+\def\@function#1(#2)#3 {
+ \begingroup
+ \setbox\arg@box=\hbox{\bf #1 \rm \((\)} \global\arg@dim\wd\arg@box
+ \setbox\arg@box=\hbox{\rm \()\);}
+ \global\line@siz\linewidth\global\advance\line@siz-\wd\arg@box
+ \pagebreak[3]
+ \expandafter\print@name#1 \@@{\rm \((\)}\def\@comma{}\ignorespaces
+ \@for\@tempa:=#2\do{\ignorespaces
+ \setbox\arg@box=\hbox{\@comma} \global\advance\arg@dim\wd\arg@box
+ \unskip\@comma\def\@comma{\nobreak,\penalty-\@m\ }\ignorespaces
+ \expandafter\print@arg\@tempa\@@\relax\ignorespaces
+ }~{\rm \()\)\nobreak#3}
+ \endgroup
+}
+
+\def\print@name#1#2 #3\@@{
+ \unskip\edef\tmp@name{#3}\ignorespaces
+ \ifx\tmp@name\@empty{\bf #1#2 }\else{\rm #1#2 \bf #3}\fi
+}
+
+\def\print@arg#1\@@{\expandafter\print@type#1 \@@}
+
+\def\print@type#1#2 #3\@@{
+ \setbox\arg@box=\hbox{{\rm #1#2}\ifx #3\@nil\else\ignorespaces
+ \expandafter\print@dummy#3=\@@\fi\unskip\/}
+ \global\advance\arg@dim\wd\arg@box
+ \ifdim\arg@dim>\line@siz
+ \global\arg@dim\argindent \global\advance\arg@dim\wd\arg@box
+ \hfill\penalty-\@m\hbox{}\kern\argindent\fi
+ \box\arg@box%
+}
+
+\def\print@dummy#1=#2\@@{
+ \edef\tmp@name{#1}\def\a@space{ }\ifx\tmp@name\a@space\else
+ {\it\ #1\/}\ifx #2\@nil\else{\rm \(=\)}\expandafter\strip@eq#2\fi
+ \fi
+}
+
+\def\strip@eq#1={{\rm #1}}
+
+\def\subtitle{\@ifstar{\@subtit@star}{\@subtit@norm}}
+
+\def\@subtit@star#1{
+ \item[\hbox{\large\bf\begin{tabular}[t]{l}#1\end{tabular}}\hfill]
+ \hfil\par
+ \expandafter{\let\par=\space\ignorespaces\let\par=\endgraf}
+}
+
+\def\@subtit@norm#1{
+ \setbox\arg@box=\hbox{\large\bf\begin{tabular}[t]{l}#1\end{tabular}}
+ \ifdim \wd\arg@box > \labelwidth \item[\copy\arg@box\hfill]\hfil\par
+ \else \dp\arg@box=0pt \item[\copy\arg@box\hfill] \fi
+ \expandafter{\let\par=\space\ignorespaces\let\par=\endgraf}
+}
+
+\newenvironment{manpage}[3]{\@beginManpage#1\@@#2\@@#3\@@}{\@endManpage}
+
+\def\@beginManpage#1\@@#2\@@#3\@@{
+ \pagestyle{headings}
+ \addcontentsline{toc}{section}{#2}
+ \clearpage
+ \gdef\@header{{#2}{#1}{#2}}
+ \gdef\@footer{{#3}{\thepage}{\today}}
+ \begin{list}{}{
+ \setlength\labelwidth{1.2in}
+ \setlength\leftmargin{\labelwidth}
+ \addtolength\leftmargin{\labelsep}
+ \topsep 5pt plus 2pt minus 2pt
+ \itemsep 5pt plus 2pt minus 2pt
+ \parsep 10pt plus 2pt minus 2pt
+ }
+ \raggedbottom
+ \let"=\arg@quote
+}
+
+\def\@endManpage{
+ \end{list} \clearpage \flushbottom
+ \let"=\tt@quote
+}
+
+\def\@first#1#2#3{#1}
+\def\@second#1#2#3{#2}
+\def\@third#1#2#3{#3}
+
+\def\ps@headings{
+ \def\@oddhead{\parbox{\textwidth}{
+ {\rm\ \ \expandafter\@first\@header\hfill
+ \expandafter\@second\@header\hfill
+ \expandafter\@third\@header\ \ } \\[.1cm]
+ \hbox{}\rule[12pt]{\textwidth}{1pt}
+ }}
+ \def\@evenhead{\parbox{\textwidth}{
+ {\rm\ \ \expandafter\@third\@header\hfill
+ \expandafter\@second\@header\hfill
+ \expandafter\@first\@header\ \ } \\[.1cm]
+ \hbox{}\rule[12pt]{\textwidth}{1pt}
+ }}
+ \def\@oddfoot{\parbox{\textwidth}{
+ \hbox{}\rule{\textwidth}{1pt} \\[.1cm]
+ {\sl\ \ \expandafter\@first\@footer\hfill
+ \rm\expandafter\@second\@footer\hfill
+ \sl\expandafter\@third\@footer\ }
+ }}
+ \def\@evenfoot{\parbox{\textwidth}{
+ \hbox{}\rule{\textwidth}{1pt} \\[.1cm]
+ {\sl\ \ \expandafter\@third\@footer\hfill
+ \rm\expandafter\@second\@footer\hfill
+ \sl\expandafter\@first\@footer\ }
+ }}
+}
+
+\gdef\@header{{}{}{}}
+\gdef\@footer{{}{}{}}
+
+\def\tableofcontents{\@restonecolfalse
+ \newskip\@savskip \@savskip=\parskip
+ \parskip 0pt plus 1pt
+ \clearpage \thispagestyle{plain} \global\@topnum\z@ \@afterindentfalse
+ \@makeschapterhead{{Contents\@mkboth{CONTENTS}{CONTENTS}}}
+ \@afterheading \@starttoc{toc}
+ \parskip=\@savskip
+}
+
+\def\@makechapterhead#1{
+ \vspace*{50pt}
+ { \raggedleft
+ \Large\bf Chapter \thechapter \par \vskip 15pt
+ \huge\bf #1\par
+ \nobreak \vskip 30pt
+ }
+}
+
+\def\@makeschapterhead#1{
+ \vspace*{50pt}
+ { \raggedleft
+ \huge\bf #1\par
+ \nobreak \vskip 30pt
+ }
+}
+
+\def\@schapter#1{
+ \addcontentsline{toc}{chapter}{#1}
+ \@makeschapterhead{#1}
+ \@afterheading
+}
+
+\catcode`\<=\active \def\mit@less{\hbox{\(\char`\<\)}} \let<=\mit@less
+\catcode`\>=\active \def\mit@more{\hbox{\(\char`\>\)}} \let>=\mit@more
+\def\<{\hbox{\(\langle\)}} \def\>{\hbox{\(\rangle\)}} \def\*{\hbox{\(\ast\)}}
+%\catcode`\_=\active \def_={\hbox{\kern.06em \vbox{\hrule width.3em}}}
+\catcode`\_=\active \global\let_=\_
+\catcode`\^=\active \def\mit@wedge{\hbox{\raise.06ex \hbox{\small \(\wedge\)}}}
+\let^=\mit@wedge
+\catcode`\+=\active \def\mit@add{\hbox{\(\char43\)}} \let+=\mit@add
+\catcode`\|=\active \def\mit@mid{\hbox{\(\mid\)}} \let|=\mit@mid
+
diff --git a/macros/latex209/contrib/manpage/example2.tex b/macros/latex209/contrib/manpage/example2.tex
new file mode 100644
index 0000000000..9492d3af95
--- /dev/null
+++ b/macros/latex209/contrib/manpage/example2.tex
@@ -0,0 +1,264 @@
+\documentstyle[11pt,twoside,manpage]{report}
+\begin{document}
+\pagestyle{headings}
+
+\begin{manpage}{OIM C++ Library}{Choice}{Version 1.0}
+
+\subtitle{Name}
+ Choice --- a set of boxes representing the choices available.
+
+\subtitle{Declaration}
+ \#include \<choice.h\>
+
+\function{Choice(Point origin, Point corner,
+ int foreground_color, int background_color,
+ int frame_style, int space_in_between,
+ int number_of_choices,
+ const~char\* first_label, $...$)}
+ Constructs a choice object. Each choice object is a set of boxes
+ representing the choices available. "Origin" and "corner" define the
+ rectangular area inside which the boxes are displayed.
+ The "space_in_between" (in pixels)
+ defines the distance between two adjacent boxes. Depending on
+ whether there is enough room to put all the choices horizontally
+ or vertically in the designated area,
+ the choices will be laid out accordingly. The
+ attributes "foreground_color", "background_color" and "frame_style"
+ define the colors for each box that represents each choice.
+ The number of labels starting with "first_label" must match the
+ number given by "number_of_choices". Each label is displayed within
+ its corresponding box. The choices are displayed
+ as soon as they are created.
+
+\function{Choice(int number_of_choices, Boolean is_horizontal = VIRTICAL)}
+ Constructs an array of choices or
+ a choice object with boxes of different sizes. The attributes
+ of the actual choices will be defined later using the
+ addItem() operation. Note: It is forbidden to have arguments
+ in the constructors of array objects in C++.
+
+\subtitle{Description}
+ A Choice object is a set of related boxes. It is used to display
+ multiple choices on the screen.
+ A choice may either be selected by pressing a hot key
+ (when mouse is not enabled) or by pressing a mouse button when the mouse
+ cursor is within the intended choice box.
+ The first highlighted character in the text label will be the
+ hot key if the mouse is not enabled, otherwise, the highlighted
+ character will have no effect. For example, label "@N@ext" designates
+ "N" as the hot key for the button if the mouse is not enabled.
+ By default, if the mouse driver is loaded before program execution,
+ the mouse is enabled.
+ When using the mouse to select
+ a choice, the selection is immediate; a hot key must be confirmed
+ by pressing ENTER (carriage return key). Arrow keys can also be used
+ to move the current selection in the direction indicated by the arrows,
+ this also requires an ENTER to confirm.
+
+\subtitle{Public \\ Operations}
+
+\function{void addItem(Point origin, Point corner,
+ int foreground_color, int background_color,
+ int frame_style, const~char\* label,
+ int text_color = WHITE,
+ int text_highlight_color = LIGHT_WHITE)}
+ Defines the attributes of a choice box in the array declared by the
+ Choice(int "number_of_choices", Boolean "is_horizontal" = VIRTICAL)
+ constructor.
+ It must be called exactly "number_of_choices"
+ times. The first call specifies the first choice, second call specifies
+ the second choice, and so on. The attributes "origin" and "corner"
+ define a box area where the choice item is located on the screen. Other
+ attributes are self-explanatory. This call is particularly useful
+ on program setup pages.
+
+\function{void disable(int index)}
+ Disables a choice box designated by "index". This means that the choice
+ can still be seen on the screen but can not be selected any more.
+ The hot key for the choice is rendered as in the normal text color rather
+ than in the highlight color. This call is often useful on a setup page,
+ where it is often necessary to have a few choices contingent upon
+ others, i.e., they are disabled first until the choices that they
+ depend upon have been initialized and then they are enabled again.
+
+\function{void enable(int index)}
+ Enables a choice box designated by "index".
+ All choices are enabled when created.
+
+\function{Boolean hasValue()}
+ Returns TRUE if the designated choice object has been selected at
+ least once. Graphically,
+ it means one of the choices is rendered in reverse colors. It is
+ sometimes necessary to check if all choice objects on a screen have
+ been selected, so that a program can go on to the next page of screen.
+ If a previous select() call is returned abnormally by pressing an ESC key,
+ this function will return FALSE. Should this occur, the previous
+ value, if any, will also be lost.
+
+\function{int selectNext()}
+ Steps through each choice of the choice object in sequential order.
+ This function is often used in implementing parameter
+ initialization screens in a controlled order. The order that the
+ choices are steped through is the same as the order of the choice
+ array. This is operator is valid only for keyboard mode. If the
+ mouse is enabled, it behaves exactly as select().
+
+\function{void setCurrent(int index)}
+ Resets the current (default) choice to the choice box indicated by
+ "index". The default choice is
+ set to the first choice box ("index" $=$ 0) when a choice object is created,
+ or the choice selected last time. This call can
+ change the default choice without having to select anything first. It will
+ affect the behavior of a selectNext() call.
+
+\function{void reset()}
+ Erases the default choice and resets the internal pointers as if this
+ choice object had never been selected before.
+
+\subtitle{Virtual \\ Operations}
+
+\function{void action(int status)}
+ Defines the behaviors of the choice object when a choice handler
+ has been bonded to the object. This function is called by the
+ event handler when it detects that the choice object has been
+ selected. The default action is to do nothing if no choice handler
+ presents, otherwise, it invokes the choice handler
+ and passes it along with the current status
+ (whatever has been returned from a status() call).
+ Do not modify this function unless it is absolutely necessary because
+ it redefines the sematics of all choice objects.
+
+\function{void bind(void \hbox{\rm (\*{\it handler})(int)})}
+ Associates a choice handler function with the choice object. Every
+ time this choice object is invoked, the choice handler is called
+ immediately.
+ The handler is passed along with the current "status"
+ (return value of status() call) as its argument. The default
+ action taken by the event handler can be modified by changing
+ the next function action().
+
+\function{Boolean isSelected(Point cursor)}
+ Returns TRUE if a legal hot key is pressed for the
+ the indicated choice object. It also returns TRUE if
+ a mouse button is pressed within the range of the choice object area.
+ This call is used by the event handler to check if this choice object
+ has been selected. It is hardly needed in regular applications.
+ The "cursor" is for mouse cursor in mouse mode or faked with the
+ current keyboard input as the cursor's x coordinate.
+
+\function{int select()}
+ Picks a choice from the choice object. If the mouse is not enabled,
+ the default choice (the one picked last time or the first one if
+ this is the first time this function is called) is displayed in
+ highlight colors. The arrow key can be used to move the
+ default choice. The ENTER key must be used to confirm the selection.
+ If the mouse is enabled,
+ this call checks if a mouse button has been pressed while the mouse
+ cursor is inside one of the choice boxes. The return value is the index
+ of the choice box selected.
+ A ESC key may be pressed
+ to leave the current select() call without actually selecting anything.
+ In this case, $-1$ will be returned.
+ Note: With no mouse enabled,
+ select() waits for either an Enter key or ESC key to return, whereas
+ with the mouse enabled, the return is immediate.
+
+\function{int status()}
+ Returns the current choice index (the one in reverse color on the screen).
+ If there is no current choice (either it has not been selected or has
+ been reset) the return value is $-1$.
+
+\subtitle{See Also}
+ Event, Button, Box
+
+\subtitle{Author}
+ Ron Chen at the Office for Information Management, UIUC. 9-1-89.
+
+\end{manpage}
+\newpage
+\begin{verbatim}
+ /* EXAMPLE 1 */
+ #include <stdlib.h>
+ #include "choice.h"
+
+ void handler1(int choice) {
+ Box box(500, 30, 600, 60, LIGHT_CYAN, LIGHT_MAGENTA);
+ box << choice + 1;
+ }
+
+ void handler2(int choice) {
+ Box box(500, 30, 600, 60, LIGHT_CYAN, LIGHT_MAGENTA);
+ box << (choice==0 ? "Ape" : (choice==1 ? "Bob" : "Car"));
+ }
+
+ void handler3(int choice) {
+ Box box(500, 30, 600, 60, LIGHT_CYAN, LIGHT_MAGENTA);
+ switch (choice) {
+ case 0: box << "D"; break; case 1: box << "E"; break;
+ case 2: box << "F"; break; case 3: box << "G"; break;
+ case 4: exit(0);
+ }
+ }
+
+ main() {
+ Point a(100, 100), b(220, 130);
+ Choice c1(a,b,BROWN,RED,ON_BORDER,0,4,"@1@","@2@","@3@","@4@");
+
+ a = Point(200, 200); b = Point(400, 230);
+ Choice c2(a,b,WHITE,BLUE,IN_BORDER,10,3,"@A@pe","@B@ob","@C@ar");
+
+ a = Point(500, 230); b = Point(550, 330);
+ Choice c3(a,b,GREEN,GRAY,NO_BORDER,10,5,"@D@","@E@","@F@","@G@","@H@");
+
+ for (int pick;;) {
+ if ((pick = c1.select()) != -1) handler1(pick);
+ if ((pick = c2.select()) != -1) handler2(pick);
+ if ((pick = c3.select()) != -1) handler3(pick);
+ }
+ }
+\end{verbatim}
+\newpage
+\begin{verbatim}
+ /* EXAMPLE 2 */
+ #include <stdlib.h>
+ #include "choice.h"
+
+ void handler1(int pick) {
+ Box box(500, 30, 600, 60, LIGHT_CYAN, LIGHT_MAGENTA);
+ box << pick + 1;
+ }
+
+ void handler2(int pick) {
+ Box box(500, 30, 600, 60, LIGHT_CYAN, LIGHT_MAGENTA);
+ box << (pick==0 ? "Ape" : (pick==1 ? "Bob" : "Car"));
+ }
+
+ void handler3(int pick) {
+ Box box(500, 30, 600, 60, LIGHT_CYAN, LIGHT_MAGENTA);
+ switch (pick) {
+ case 0: box << "D"; break; case 1: box << "E"; break;
+ case 2: box << "F"; break; case 3: box << "G"; break;
+ case 4: exit(0);
+ }
+ }
+
+ main() {
+ Point a(100, 100), b(220, 130);
+ Choice c1(a,b,BROWN,RED,ON_BORDER,0,4,"@1@","@2@","@3@","@4@");
+ Choice c2(3, HORIZONTAL);
+ c2.addItem(Point(200, 200), Point(260,230),
+ WHITE, BLUE, IN_BORDER, "@A@pe");
+ c2.addItem(Point(270, 200), Point(330,230),
+ WHITE, BLUE, IN_BORDER, "@B@ob");
+ c2.addItem(Point(340, 200), Point(400,230),
+ WHITE, BLUE, IN_BORDER, "@C@ar");
+ a = Point(500, 230); b = Point(550, 330);
+ Choice c3(a,b,GREEN,GRAY,NO_BORDER,10,5,"@D@","@E@","@F@","@G@","@H@");
+
+ c1.bind(handler1);
+ c2.bind(handler2);
+ c3.bind(handler3);
+ Event::waitForEvents();
+ }
+\end{verbatim}
+\end{document}
diff --git a/macros/latex209/contrib/manpage/manpage.sty b/macros/latex209/contrib/manpage/manpage.sty
new file mode 100644
index 0000000000..500ee7f670
--- /dev/null
+++ b/macros/latex209/contrib/manpage/manpage.sty
@@ -0,0 +1,342 @@
+%%% ====================================================================
+%%% @LaTeX-style-file{
+%%% author = "Rong Chen",
+%%% version = "1.03",
+%%% date = "11 June 1992",
+%%% time = "15:16:26 CDT",
+%%% filename = "manpage.sty",
+%%% address = "Department of Computer Science
+%%% University of Illinois at Urbana-Champaign
+%%% 1304 W. Springfield Ave.
+%%% Urbana, IL 61801
+%%% USA",
+%%% telephone = "(217) 244-7118",
+%%% FAX = "(217) 333-3501",
+%%% checksum = "03245 575 2732 22501",
+%%% email = "rchen@cs.uiuc.edu (Internet)",
+%%% codetable = "ISO/ASCII",
+%%% keywords = "LaTeX, manpage",
+%%% supported = "yes",
+%%% docstring = "This LaTeX style file is similar to the UNIX troff
+%%% man macros in format and is specially tuned for
+%%% documenting the C++ library that the author wrote.
+%%%
+%%% This style option is designed to work with both
+%%% report and article document styles of LaTeX v2.09,
+%%% e.g., \documentstyle[11pt,twoside,manpage]{report}
+%%%
+%%% The checksum field above contains a CRC-16
+%%% checksum as the first value, followed by
+%%% the equivalent of the standard UNIX wc
+%%% (word count) utility output of lines,
+%%% words, and characters. This is produced by
+%%% Robert Solovay's checksum utility.",
+%%% }
+%%% ====================================================================
+
+% manpage.sty
+%
+% Copyright (c) 1990 by Rong Chen (rchen@cs.uiuc.edu)
+% Permission to copy all or part of this work is granted, provided
+% that the copies are not made or distributed for resale, and that
+% the copyright notice and this notice are retained.
+%
+% THIS WORK IS PROVIDED ON AN "AS IS" BASIS. THE AUTHOR PROVIDES NO
+% WARRANTY WHATSOEVER, EITHER EXPRESS OR IMPLIED, REGARDING THE WORK,
+% INCLUDING WARRANTIES WITH RESPECT TO ITS MERCHANTABILITY OR FITNESS
+% FOR ANY PARTICULAR PURPOSE.
+
+%
+% The commands defined in the style file are listed bellow:
+%
+% \begin{manpage}{Title}{Module}{Version} % see an example, all will be clear
+% % latex supplies the current date if no \date{} is specified
+% \end{manpage} % end of manpage environment
+% \variable{#1} (e.g., \variable{int foo}) % with \medskip added
+% \variable*{#1} (e.g., \variable*{int bar})% no extra spacing
+% \function{#1} (e.g., \function{void demo(int dummy)}) % with \medskip added
+% \function*{#1} (e.g., \function*{void demo(int dummy)})% no extra spacing
+% \subtitle{#1} (e.g., \subtitle{AUTHOR}) % fit in the same line if possible
+% \subtitle*{#1} (e.g., \subtitle*{AUTHOR})% always break a newline
+% "#1" (e.g., "dummy_variable") % argument is in italic&unbreakable
+% \separator % draw a thin line to separate subtitle from the text
+% \header{#1}{#2}{#3} % in case you want to have a header and
+% \footer{#1}{#2}{#3} % a footer outside of the manpage environment
+%
+% In the \function macro, data types and their dummy arguments are separated
+% by a space. So if you have a function like "int f(const int n)", you should
+% document it as \function{int f(const~int n)}. The argument n is optional.
+% In the \subtitle macro, two lines of text may be divided by "\\".
+%
+% The following characters (control-sequents) are defined (or redefined) as:
+%
+% \" --- print the double quote character ("), use $\ddot{\rm#1}$ for accent
+% \~ --- defined as $\sim$ being raised 0.6ex, use $\tilde{\rm#1}$ for accent
+% \* --- the same as $\ast$
+% \< --- the same as $\langle$
+% \> --- the same as $\rangle$
+% < --- the same as $<$
+% > --- the same as $>$
+% _ --- the same as \_, use $\sb{#1}$ for subscript (see TeXbook pp. 135)
+% + --- the same as $+$
+% | --- the same as $\mid$
+% ^ --- {\small $\wedge$} being raised 0.6ex, superscript is now $\sp{#1}$
+% " --- the same as {\tt "} when outside of the manpage environment,
+% otherwise use \" instead
+
+\headheight 24pt % see Lamport's LaTeX book for definitions
+\headsep 12pt
+\textwidth 6.25in
+\textheight 8.0in
+\topmargin 0in
+\marginparwidth 0pt
+\oddsidemargin 0pt
+\evensidemargin 0pt
+\marginparsep 0pt
+\parindent 0pt
+\parskip 10pt plus 1pt
+
+\newdimen\funindent \funindent 0pt % indentation for function/variable entries
+\newdimen\argindent \argindent -1pt % indentation for function arguments
+
+% when \argindent >= 0pt, subsequent lines of arguments have fixed indentation
+% i.e., \argindent (e.g., 3em). See the following example:
+% int foo ( int x, int y, int w,
+% int h, char a, char b,
+% char c, char d )
+%
+% when \argindent < 0pt (value doesn't matter), arguments are auto-indented:
+% int foo ( int x, int y, int w,
+% int h, char a, char b,
+% char c, char d )
+
+% \tableofcontents and \chapter macros are also modified in manpage.sty.
+% The standard LaTeX \tableofcontents couldn't handle \chapter* correctly.
+% In the table of contents each manpage has the same indentation as a section.
+% Chapter titles have smaller font and they are pushed to the right margin.
+
+% > From: Vick Khera <khera@cs.duke.edu>
+% > one more thing you may like... we have this cprog.sty style
+% > (formatting of C programs, by \'Eamonn McManus <emcmanus@cs.tcd.ie>)
+% > that lets you place C, C++, Pascal, and Modula-2 source code in your
+% > LaTeX source directly. no more verbatim mode, which i think is ugly
+% > for C code. just be sure to include it *before* you include manpage.sty
+% > or things break. i don't know why, but i can live with it:
+% > \documentstyle[cprog,manpage]{report} will do the trick. then just replace
+% > those pesky \begin{verbatim}\end{verbatim} with \begin{cprog}\end{cprog}
+% > and it looks much better. i also like to put after the \documentstyle
+% > the command \let\ctextfont=\sf so the code is typeset in the \sf font
+% > to differentiate it from normal text.
+% (you may do the same with \let\ccommentfont=\sl and \let\cstringfont=\sf)
+
+% If you make any improvements, I'd like to hear about them.
+%
+% STOP STOP STOP -- comments end here :-(
+% but there is a sample.tex file in the back.
+
+\newcommand{\header}[3]{\gdef\@header{{#1}{#2}{#3}}}
+\newcommand{\footer}[3]{\gdef\@footer{{#1}{#2}{#3}}}
+
+\def\separator{\rule{\linewidth}{0.5pt}}
+
+\catcode`\"=\active
+\def\arg@quote#1"{\hbox{\it #1\/}}
+\def\tt@quote{\hbox{\tt \char34}}
+\let"=\tt@quote
+\let\"=\tt@quote
+
+\def\variable{\pagebreak[3]\@ifstar{\var@star}{\var@norm}}
+\def\var@star#1{\expandafter\print@var#1\@@\\ }
+\def\var@norm#1{\expandafter\print@var#1\@@\medskip\\ }
+
+\def\print@var#1\@@{\expandafter\parse@var#1 =\@@}
+\def\parse@var#1=#2\@@{
+ \print@name#1\@@
+ \ifx #2\@nil\else{\unskip\rm\ \(=\)\ }\strip@eq#2\fi
+}
+
+\def\function{\pagebreak[3]\@ifstar{\@func@star}{\@func@norm}}
+\def\@func@star#1{\expandafter\@function#1 \\ }
+\def\@func@norm#1{\expandafter\@function#1 \medskip\\ }
+
+\newdimen\arg@dim % temp variables that you don't want to know
+\newdimen\arg@indent
+\newdimen\line@siz
+\newbox\arg@box
+
+\def\@function#1(#2)#3 {
+ \expandafter\print@name#1 \@@
+ \setbox\arg@box=\hbox{\rm\ \((\)\ }%
+ \global\advance\arg@dim\wd\arg@box
+ \unskip\box\arg@box
+ \edef\@fortmp{#2}%
+ \ifx\@fortmp\@empty {\rm \()\)#3}\else
+ \setbox\arg@box=\hbox{\rm\ \()\);}%
+ \global\line@siz\linewidth \global\advance\line@siz-\wd\arg@box
+ \ifdim\argindent<0pt
+ \global\arg@indent\arg@dim \else\global\arg@indent\argindent\fi
+ \def\@comma{}%
+ \@for\@tempa:=#2\do{%
+ \setbox\arg@box=\hbox{\@comma}%
+ \global\advance\arg@dim\wd\arg@box
+ \unskip\@comma\def\@comma{\nobreak,\penalty-\@m\ }%
+ \expandafter\print@arg\@tempa\@@
+ }%
+ \unskip\nobreak\hbox{\rm\ \()\)#3}%
+ \fi
+}
+
+\def\print@name#1#2 #3\@@{%
+ \edef\tmp@name{#3}%
+ \ifx\tmp@name\@empty
+ \setbox\arg@box=\hbox{\bf #1#2}%
+ \else\setbox\arg@box=\hbox{\rm #1#2 \bf #3\unskip}\fi
+ \global\arg@dim\funindent \global\advance\arg@dim\wd\arg@box
+ \unskip\hspace{\funindent}\box\arg@box
+}
+
+\def\print@arg#1\@@{\expandafter\print@type#1 \@@}
+
+\def\print@type#1#2 #3\@@{%
+ \setbox\arg@box=\hbox{{\rm #1#2}%
+ \ifx #3\@nil\else\expandafter\print@dummy#3=\@@\fi
+ \unskip\/}%
+ \global\advance\arg@dim\wd\arg@box
+ \ifdim\arg@dim>\line@siz
+ \global\arg@dim\arg@indent \global\advance\arg@dim\wd\arg@box
+ \hfill\penalty-\@m\hbox{}\kern\arg@indent\fi
+ \box\arg@box
+}
+
+\def\print@dummy#1=#2\@@{%
+ \edef\tmp@name{#1}\def\a@space{ }%
+ \ifx\tmp@name\a@space\else
+ {\unskip\it\ #1\/}%
+ \ifx #2\@nil\else{\unskip\rm\ \(=\)\ }\strip@eq#2\fi
+ \fi
+}
+
+\def\strip@eq#1={\rm \expandafter\ignorespaces#1\unskip}
+
+\def\subtitle{\pagebreak[3]\@ifstar{\@subtit@star}{\@subtit@norm}}
+
+\def\@subtit@star#1{
+ \item[\hbox{\large\bf\begin{tabular}[t]{l}#1\end{tabular}}\hfill]
+ \hfil\par
+ \expandafter{\let\par=\space\ignorespaces\let\par=\endgraf}
+}
+
+\def\@subtit@norm#1{
+ \setbox\arg@box=\hbox{\large\bf\begin{tabular}[t]{l}#1\end{tabular}}
+ \ifdim \wd\arg@box > \labelwidth \item[\copy\arg@box\hfill]\hfil\par
+ \else \dp\arg@box=0pt \item[\copy\arg@box\hfill] \fi
+ \expandafter{\let\par=\space\ignorespaces\let\par=\endgraf}
+}
+
+\newenvironment{manpage}[3]{\@beginManpage#1\@@#2\@@#3\@@}{\@endManpage}
+
+\def\@beginManpage#1\@@#2\@@#3\@@{
+ \newpage
+ \pagestyle{headings}
+ \addcontentsline{toc}{section}{#2}
+ \clearpage
+ \gdef\@header{{#2}{#1}{#2}}
+ \gdef\@footer{{#3}{\thepage}{\@date}}
+ \begin{list}{}{
+ \setlength\labelwidth{1.2in}
+ \setlength\leftmargin{\labelwidth}
+ \addtolength\leftmargin{\labelsep}
+ \topsep 5pt plus 2pt minus 2pt
+ \itemsep 5pt plus 2pt minus 2pt
+ \parsep 10pt plus 2pt minus 2pt
+ }
+ \raggedbottom
+ \let"=\arg@quote
+}
+
+\def\@endManpage{
+ \end{list} \clearpage \flushbottom
+ \let"=\tt@quote
+}
+
+\def\@first#1#2#3{#1}
+\def\@second#1#2#3{#2}
+\def\@third#1#2#3{#3}
+
+\def\ps@headings{
+ \def\@oddhead{\parbox{\textwidth}{
+ {\rm\ \ \expandafter\@first\@header\hfill
+ \expandafter\@second\@header\hfill
+ \expandafter\@third\@header\ \ } \\[.1cm]
+ \hbox{}\rule[12pt]{\textwidth}{1pt}
+ }}
+ \def\@evenhead{\parbox{\textwidth}{
+ {\rm\ \ \expandafter\@third\@header\hfill
+ \expandafter\@second\@header\hfill
+ \expandafter\@first\@header\ \ } \\[.1cm]
+ \hbox{}\rule[12pt]{\textwidth}{1pt}
+ }}
+ \def\@oddfoot{\parbox{\textwidth}{
+ \hbox{}\rule{\textwidth}{1pt} \\[.1cm]
+ {\sl\ \ \expandafter\@first\@footer\hfill
+ \rm\expandafter\@second\@footer\hfill
+ \sl\expandafter\@third\@footer\ }
+ }}
+ \def\@evenfoot{\parbox{\textwidth}{
+ \hbox{}\rule{\textwidth}{1pt} \\[.1cm]
+ {\sl\ \ \expandafter\@third\@footer\hfill
+ \rm\expandafter\@second\@footer\hfill
+ \sl\expandafter\@first\@footer\ }
+ }}
+}
+
+\gdef\@header{{}{}{}}
+\gdef\@footer{{}{}{}}
+
+\def\tableofcontents{\@restonecolfalse
+ \newskip\@savskip \@savskip=\parskip
+ \parskip 0pt plus 1pt
+ \clearpage \thispagestyle{plain} \global\@topnum\z@ \@afterindentfalse
+ \@makeschapterhead{{Contents\@mkboth{CONTENTS}{CONTENTS}}}
+ \@afterheading \@starttoc{toc}
+ \parskip=\@savskip
+}
+
+\def\@makechapterhead#1{
+ \vspace*{50pt}
+ { \raggedleft
+ \Large\bf \@chapapp{} \thechapter \par \vskip 15pt
+ \huge\bf #1\par
+ \nobreak \vskip 30pt
+ }
+}
+
+\def\@makeschapterhead#1{
+ \vspace*{50pt}
+ { \raggedleft
+ \huge\bf #1\par
+ \nobreak \vskip 30pt
+ }
+}
+
+\def\@schapter#1{
+ \addcontentsline{toc}{chapter}{#1}
+ \@makeschapterhead{#1}
+ \@afterheading
+}
+
+\catcode`\<=\active \def\mit@less{\hbox{\(\char60\)}} \let<=\mit@less
+\catcode`\>=\active \def\mit@more{\hbox{\(\char62\)}} \let>=\mit@more
+\def\<{\(\langle\)}
+\def\>{\(\rangle\)}
+\def\*{\(\ast\)}
+\def\~{\(\raise.6ex\hbox{\(\sim\)}\)}
+% \catcode`\_=\active \def_={\hbox{\kern.1em\vbox{\hrule width.3em}}}
+\catcode`\_=\active \global\let_=\_
+\def\mit@wedge{\hbox{\raise.6ex\hbox{\small \(\wedge\)}}}
+\catcode`\^=\active \let^=\mit@wedge
+\catcode`\+=\active \def\mit@add{\hbox{\(\char43\)}} \let+=\mit@add
+\catcode`\|=\active \def\mit@mid{\hbox{\(\mid\)}} \let|=\mit@mid
+
+\endinput
+
diff --git a/macros/latex209/contrib/manpage/sample.tex b/macros/latex209/contrib/manpage/sample.tex
new file mode 100644
index 0000000000..c01fb1bd3c
--- /dev/null
+++ b/macros/latex209/contrib/manpage/sample.tex
@@ -0,0 +1,230 @@
+% \documentstyle[11pt,twoside,manpage]{report}
+% \begin{document}
+% \date{November 25, 1990}
+%
+% \begin{titlepage}
+% \vspace*{1.0in}
+% \begin{flushright}
+% {\huge\bf OIM C++ Library} \\[.25cm]
+% {\rule[.1in]{4.5in}{.02in}}\\[.25cm]
+% {\large\bf Reference Manual} \\[2.0cm]
+% {\large\bf Version 1.0} \\[4.0cm]
+% {\bf Rong Chen}\\[1.0cm]
+% {Research Services}\\
+% {Office for Information Management}\\
+% {1407 W. Gregory Drive}\\
+% {Urbana, IL 61801}\\
+% {(217)--244--8538}\\
+% \end{flushright}
+% \end{titlepage}
+%
+% \pagenumbering{roman}
+% \tableofcontents
+%
+% \chapter*{Preface}
+%
+% Object-oriented problem solving and object-oriented programming
+% represent a way of thinking and a methodology for computer
+% programming that are quite different from the traditional approaches
+% supported by structured programming languages. The powerful
+% features of object-oriented programming support the concepts that
+% make computer problem solving a more human-like activity and
+% that increase the re-usability of software code. As object-oriented
+% languages become steadily available, object-oriented programming
+% is becoming more and more popular among both system developers
+% and application programmers.
+%
+% \newpage
+%
+% \raggedbottom
+% \pagenumbering{arabic}
+% \pagestyle{headings}
+% \chapter*{Class Descriptions}
+%
+% \begin{manpage}{OIM C++ Library}{Choice}{Version 1.0}
+%
+% \subtitle{Name}
+% Choice --- a set of boxes representing the choices available.
+%
+% \subtitle{Declaration}
+% \#include \<choice.h\>
+%
+% \function{Choice(Point origin, Point corner,
+% int foreground_color, int background_color,
+% int frame_style, int space_in_between,
+% int number_of_choices,
+% const~char\* first_label, $...$ )}
+% Constructs a choice object. Each choice object is a set of boxes
+% representing the choices available. The "origin" and "corner"
+% define the rectangular area inside which the boxes are displayed.
+% The "space_in_between" (in pixels)
+% defines the distance between two adjacent boxes. Depending on
+% whether there is enough room to put all the choices horizontally
+% or vertically in the designated area,
+% the choices will be laid out accordingly. The
+% attributes "foreground_color", "background_color" and "frame_style"
+% define the colors for each box that represents each choice.
+% The number of labels starting with "first_label" must match the
+% number given by "number_of_choices". Each label is displayed within
+% its corresponding box. The choices are displayed
+% as soon as they are created.
+%
+% \function{Choice(int number_of_choices, Boolean is_horizontal = VERTICAL)}
+% Constructs an array of choices or
+% a choice object with boxes of different sizes. The attributes
+% of the actual choices will be defined later using the
+% addItem() operation. Note: It is forbidden to have arguments
+% in the constructors of array objects in C++.
+%
+% \function{\~Choice()}
+% Choice class has an empty destructor.
+%
+% \subtitle{Description}
+% A Choice object is a set of related boxes. It is used to display
+% multiple choices on the screen.
+% A choice may either be selected by pressing a hot key
+% (when mouse is not enabled) or by pressing a mouse button when the mouse
+% cursor is within the intended choice box.
+% The first highlighted character in the text label will be the
+% hot key if the mouse is not enabled, otherwise, the highlighted
+% character will have no effect. For example, label "@N@ext" designates
+% "N" as the hot key for the button if the mouse is not enabled.
+% By default, if the mouse driver is loaded before program execution,
+% the mouse is enabled. When using the mouse to select
+% a choice, the selection is immediate; a hot key must be confirmed
+% by pressing ENTER (carriage return key). Arrow keys can also be used
+% to move the current selection in the direction indicated by the arrows,
+% this also requires an ENTER to confirm.
+%
+% \subtitle{Global \\ Variables}
+% \variable{char host_name[20] = \"rose.cs.uiuc.edu\"}
+% The "host_name" buffer is initialized to the current machine name
+% before the main() function is executed. The machine name is
+% usually declared in a DOS shell variable "OIMUSER".
+%
+% \variable{Boolean mouse_installed}
+% By default, the "mouse_installed" variable is assigned to TRUE if
+% the mouse driver has been installed before program execution;
+% otherwise it is assigned to FALSE. The value may also be changed
+% through enableMouse() and disableMouse() functions.
+%
+% \subtitle{Macros}
+% \function{MAX({\it x}, {\it y})}
+% Returns the maximum of the two comparable objects "x", and "y".
+% This macro is often used to compare integers or real numbers.
+%
+% \function{MIN({\it x}, {\it y})}
+% Returns the minimum of the two comparable objects "x", and "y".
+% This macro is often used to compare integers or real numbers.
+%
+% \subtitle{Public \\ Operations}
+% \function{void addItem(Point origin, Point corner,
+% int foreground_color, int background_color,
+% int frame_style, const~char\* label,
+% int text_color = WHITE,
+% int text_highlight_color = LIGHT_WHITE)}
+% Defines the attributes of a choice box in the array declared by the
+% Choice(int "number_of_choices", Boolean "is_horizontal" = VERTICAL)
+% constructor. It must be called exactly "number_of_choices"
+% times. The first call specifies the first choice, second call specifies
+% the second choice, and so on. The attributes "origin" and "corner"
+% define a box area where the choice item is located on the screen. Other
+% attributes are self-explanatory. This call is particularly useful
+% on program setup pages.
+%
+% \function{Boolean hasValue()}
+% Returns TRUE if the designated choice object has been selected at
+% least once. Graphically,
+% it means one of the choices is rendered in reverse colors. It is
+% sometimes necessary to check if all choice objects on a screen have
+% been selected, so that a program can go on to the next page of screen.
+% If a previous select() call is returned abnormally by pressing an ESC
+% key, this function will return FALSE. Should this occur, the previous
+% value, if any, will also be lost.
+%
+% \subtitle{Virtual \\ Operations}
+%
+% \function{void action(int status)}
+% Defines the behaviors of the choice object when a choice handler
+% has been bonded to the object. This function is called by the
+% event handler when it detects that the choice object has been
+% selected. The default action is to do nothing if no choice handler
+% presents, otherwise, it invokes the choice handler
+% and passes it along with the current status
+% (whatever has been returned from a status() call).
+% Do not modify this function unless it is absolutely necessary because
+% it redefines the semantics of all choice objects.
+%
+% \function{void bind(void \hbox{\rm (\*{\it handler})(int)})}
+% Associates a choice handler function with the choice object. Every
+% time this choice object is invoked, the choice handler is called
+% immediately.
+% The handler is passed along with the current "status"
+% (return value of status() call) as its argument. The default
+% action taken by the event handler can be modified by changing
+% the next function action().
+%
+% \function{Boolean isSelected(Point cursor)}
+% Returns TRUE if a legal hot key is pressed for the
+% the indicated choice object. It also returns TRUE if
+% a mouse button is pressed within the range of the choice object area.
+% This call is used by the event handler to check if this choice object
+% has been selected. It is hardly needed in regular applications.
+% The "cursor" is for mouse cursor in mouse mode or faked with the
+% current keyboard input as the cursor's x coordinate.
+%
+% \subtitle{See Also}
+% Event, Button, Box
+%
+% \subtitle{Author}
+% Rong Chen at the Office for Information Management, UIUC. 9-1-89.
+%
+% \end{manpage}
+% \newpage
+% \begin{verbatim}
+% #include <stdlib.h>
+% #include "choice.h"
+%
+% void handler1(int pick) {
+% Box box(500, 30, 600, 60, LIGHT_CYAN, LIGHT_MAGENTA);
+% box << pick + 1;
+% }
+%
+% void handler2(int pick) {
+% Box box(500, 30, 600, 60, LIGHT_CYAN, LIGHT_MAGENTA);
+% box << (pick==0 ? "Ape" : (pick==1 ? "Bob" : "Car"));
+% }
+%
+% void handler3(int pick) {
+% Box box(500, 30, 600, 60, LIGHT_CYAN, LIGHT_MAGENTA);
+% switch (pick) {
+% case 0: box << "D"; break; case 1: box << "E"; break;
+% case 2: box << "F"; break; case 3: box << "G"; break;
+% case 4: exit(0);
+% }
+% }
+%
+% main() {
+% Point a(100, 100), b(220, 130);
+% Choice c1(a, b, BROWN, RED, ON_BORDER, 0, 4,
+% "@1@", "@2@", "@3@", "@4@");
+% Choice c2(3, HORIZONTAL);
+% c2.addItem(Point(200, 200), Point(260,230),
+% WHITE, BLUE, IN_BORDER, "@A@pe");
+% c2.addItem(Point(270, 200), Point(330,230),
+% WHITE, BLUE, IN_BORDER, "@B@ob");
+% c2.addItem(Point(340, 200), Point(400,230),
+% WHITE, BLUE, IN_BORDER, "@C@ar");
+% a = Point(500, 230); b = Point(550, 330);
+% Choice c3(a, b, GREEN, GRAY, NO_BORDER, 10, 5,
+% "@D@", "@E@", "@F@", "@G@", "@H@");
+% c1.bind(handler1);
+% c2.bind(handler2);
+% c3.bind(handler3);
+%
+% waitForEvents();
+% }
+% \end{verbatim}
+%
+% \end{document}
+%===========================[End of sample.tex]=============================