flx/docs/flx.tex

%  %  %  %  %  %  %  %  %  %  %  %  %  %  %  %  %  %  %  %  %  %  %  %  %  %  %
%
%  This document describes flx - a library of routines that extend the
%  functionality of xforms.  It is for input to the wordprocessor LaTeX.
%  You will need to run LaTeX twice in order to obtain a correct table of
%  contents.
%
%  %  %  %  %  %  %  %  %  %  %  %  %  %  %  %  %  %  %  %  %  %  %  %  %  %  %

\font\button = cmssbx10

% twoside requires LaTeX version 2 epsilon?
\documentstyle[12pt, twoside, epsf]{article}

% Left margin   = 1.5in
% Right margin  = 1.0in
% Top margin    = 0.75in
% Bottom margin = 1.0in

\setlength{\textwidth}{6.0in}
\setlength{\evensidemargin}{0.0in}
\setlength{\oddsidemargin}{0.5in}
\setlength{\headsep}{20pt}
\setlength{\headheight}{12pt}
\setlength{\topmargin}{-0.25in}
\setlength{\footskip}{26pt}
\setlength{\footheight}{12pt}
\setlength{\intextsep}{15pt}

\setlength{\parindent}{0pt}
\setlength{\parskip}{10pt}

% Vertical space around inserted figures
\setlength{\textfloatsep}{15pt}
\setlength{\intextsep}{15pt}

% Set penalties for a line by itself at the bottom of a page and
% breaking a page just before the last line of a paragraph.
\clubpenalty 10000
\widowpenalty 10000


\newcommand{\clearemptydoublepage}{\newpage{\pagestyle{empty}\cleardoublepage}}
\newcommand{\flx}{{\bf{flx\ }}}
\newcommand{\code}[1]{{\texttt{#1}}}

\pagestyle{headings}
\pagenumbering{roman}
\setcounter{section}{0}


% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
\begin{document}


% Title page
\thispagestyle{empty}
\begin{center}
      \begin{figure}[!hbt]
            \leavevmode\epsffile{figures/flx.ps}
            \vspace{1cm}
      \end{figure}
      \large
      Version 0.1                           \\
      Document: 1998 January                \\
      \vspace{1.0cm}
      Robert S. Mallozzi                    \\
      University of Alabama in Huntsville   \\
      currently at                          \\
      NASA Marshall Space Flight Center     \\
      \vspace{0.5cm}
      mallozzi@cspar.uah.edu                \\
      http://cspar.uah/edu/$\sim$mallozzir/ \\

\end{center}

\normalsize


\vspace*{\fill}
\newpage

% Generate a blank page
\thispagestyle{empty}
\mbox{}
\newpage

% Table of contents
\setcounter{page}{1}
\tableofcontents
\clearpage

% Generate a blank page
%\mbox{}
%\newpage

% Begin main text - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
\section{Introduction}

\hrule
\vspace{0.5cm}

\setcounter{page}{0}
\pagenumbering{arabic}

% % % % % % % % % % % % % % % % % % % % % % % % % % % % % % % % % % % % % % % %
%
\subsection{Overview}

\flx is a library of routines that augments the functionality of the xforms
library.  It consists of two main sections:
%
\begin{itemize}
    \item[] {\sl Objects} \\
            Functions that implement user--defined objects and widget
            applications.
    \item[] {\sl Utilities} \\
            Functions intended to help programmers as they
            develop their own interfaces using the xforms library.
\end{itemize}


\subsection{Design Goals and Request for Contributions}

Development of \flx was undertaken to provide additional routines  that are not
present in xforms, and to provide alternatives to some of the built--in
routines of xforms.  The authors of xforms designed that library to be easily
extended with user--defined objects; \flx is an attempt to gather togther some
objects that have been designed by the users of xforms and utility routines into
one convenient package.  Therefore, contributions to \flx are requested.  If
you have designed a new xforms object, or if you have some utility routines
that you think would be of use to others, submit them to
\begin{quote}
      mallozzir@cspar.uah.edu \\
      Subject: flx submission
\end{quote}
for integration into \flx. Please provide the source
code, a README file that explains the purpose of the utility, and if possible,
a small example program that demonstrates the routine.  It is my hope that \flx
will become a useful and convenient extension of xforms.  To do so,
contributions from others are required!

Note that utility routines should be xforms oriented.  That is, general
c programming utility routines are not considered relevant for the \flx
library.


\subsection{Support}

Although \flx routines are tested, software errors are inevitable.  Please
send reports of code errors, or feature requests and suggestions to
\begin{quote}
      mallozzir@cspar.uah.edu \\
      Subject: flx bug report
\end{quote}
All comments will be greatly appreciated.  Development of \flx occurs on a
Pentium running RedHat Linux 2.0.27.  Testing under other platforms is
restricted due to limited access to computers running other operating systems.


\subsection{Legal}

Permission to use, copy, and distribute this software for any purpose  and
without fee is hereby granted, provided that the author's name and this notice
appear in all copies and in supporting documentation. All distributions must
include the original, unmodified source code. If the software is modified,
notice of modifications must be given. The author's name shall not be otherwise
used publicity pertaining to  distribution of the software without specific,
written prior permission.

The software is provided to you ``as--is'', and without warranty of any kind,
express, implied or otherwise, including without limitation, any warranty
of merchantability or fitness for a particular purpose.  In no event shall
the author be liable to you or anyone else for any direct, special,
incidental, indirect or consequential damages of any kind, or any damages
whatsoever, including without limitation, loss of profit, loss of use,
savings or revenue, or the claims of third parties, whether or not the
author has been advised of the possibility of such loss, however caused
and on any theory of liability, arising out of or in connection with the
possession, use or performance of this software.

This software is in no way affiliated with the University of Alabama,
NASA and the US government, or the authors of the xforms library.

The following is paraphrased from the xforms manual, and summarizes the
xforms software license:

\begin{quote}

{\bf Forms Library} is {\em not} public domain.  It is copyright by T.C.\ Zhao
and Mark Overmars, with all published and unpublished rights reserved.  However,
permission to use for non--commercial and not-for-profit purposes is granted.
You may not use xforms commercially (including in-house and contract/consulting
use) without contacting (\code{xforms@world.std.com}) for a license
arrangement.  Use of xforms for the sole purpose of running a publically
available free software that requires it is not considered a commercial use.

\end{quote}


% % % % % % % % % % % % % % % % % % % % % % % % % % % % % % % % % % % % % % % %
%
\newpage
\section{Objects}

\hrule
\vspace{0.5cm}


\subsection{flx\_filebox}

\code{flx\_filebox} is a file selection box that offers an alternative to
the file selector that is part of xforms.
To add an \code{flx\_filebox}, use the routine
%
{\ttfamily{
\begin{quote}\begin{tabbing}
    char *flx\_filebox ( \= const char *directory, \\
                         \> const char *pattern, \\
                         \> const char *default\_file )
\end{tabbing}\end{quote}
}}
%
Files in directory \code{directory} that match the pattern \code{pattern} will
be shown in the form (see Figure~\ref{fig:flx_filebox}).   \code{default\_file}
is the default file name.  Only a single selector can be visible on the screen
at a time, and there is currently no facility for selecting multiple files.
%
\begin{figure}[!hbt]
\begin{center}
%      \epsfxsize=5in
      \leavevmode\epsffile{figures/flxfilebox.ps}
      \nobreak
      \caption{
      \code{flx\_filebox}
      }
      \vspace{0.35in}
      \label{fig:flx_filebox}
\end{center}
\end{figure}
%
A filename can be selected by highlighting an entry with a single mouse click,
and then selecting ``Ok''.  Alternatively, one can double click on the filename
to immediately select the entry and return to the application program.

The directory structure can be navigated by single clicking on directory
entries in the left browser box.  The right browser will be updated with the
file list from the new directory.

Color filetypes are supported in \code{flx\_filebox}.  For example, regular
files and directories are shown in black, symbolic links in cyan, etc.
Selecting the ``Help'' button will invoke an \code{flx\_help\_dialog} (see
below) that lists the filetype colors, and instructions for using
\code{flx\_filebox}.


\subsection{flx\_help\_dialog}

\code{flx\_help\_dialog} is a utility used to display a simple help form.
The function creates a form that displays the specified text, and a ``Dismiss''
button.  The text can have embedded newline characters, and the form width
will be based on the widest line.  Thus, for an aesthetically pleasing help
form, you should try to make the text lines roughly the same length.
To add an \code{flx\_help\_dialog}, use the routine
%
{\ttfamily{
\begin{quote}\begin{tabbing}
    FL\_FORM *flx\_help\_dialog ( \= const char *help\_text )
\end{tabbing}\end{quote}
}}
%
The function returns a pointer to the help dialog object.
The help dialog that is used in \code{flx\_filebox} is shown in
Figure~\ref{fig:flx_help_dialog}.
%
\begin{figure}[!hbt]
\begin{center}
%      \epsfxsize=5in
      \leavevmode\epsffile{figures/flxhelpdialog.ps}
      \nobreak
      \caption{
      flx\_help\_dialog
      }
      \vspace{0.35in}
      \label{fig:flx_help_dialog}
\end{center}
\end{figure}


\subsection{flx\_return\_button}

\code{flx\_return\_button} implements a default return button that is similar
in appearance to the Motif default button.  For an example of the appearance of
an \code{flx\_return\_button}, see Figure~\ref{fig:flx_help_dialog}.  Pressing
the $<$Return$>$ key when the form has window focus will invoke the callback
function that you attach to the \code{flx\_return\_button}.  Note that if you
create a form that contains both an \code{flx\_return\_button} and a text input
object, the $<$Return$>$ button can no longer be used to invoke the text input
callback.  For one example of how to avoid conflicts between return buttons and
text input objects, see \code{flx\_filebox.c}.


\subsection{flx\_show\_dialog}

\code{flx\_show\_dialog} implements a set of popup dialog widgets whose
function is similar to that of the \code{fl\_goodies} dialogs.  Currently the
following types of dialogs are supported:
%
\begin{itemize}
      \item[] error
      \item[] info
      \item[] question
      \item[] message
      \item[] warning
\end{itemize}
%
To invoke an \code{flx\_show\_dialog}, use the following function:
%
{\ttfamily{
\begin{quote}\begin{tabbing}
     int flx\_show\_dialog ( \= const char *key, \\
                             \> const char *text )
\end{tabbing}\end{quote}
}}
%
{\ttfamily key} is a pointer to one of the strings from the list above that
denotes the type of dialog, and {\ttfamily text} is a pointer to the text that
should appear in the dialog, which may have embedded newline characters.
To set attributes of the dialogs, use the following routines
before the call to \code{flx\_show\_dialog}.

To set the color of the dialog text:
%
{\ttfamily{
\begin{quote}\begin{tabbing}
    flx\_set\_dialog\_lcol ( FL\_COLOR label\_color ) \\
\end{tabbing}\end{quote}
}}

To set the dialog button inactive and active colors:
%
{\ttfamily{
\begin{quote}\begin{tabbing}
    flx\_set\_dialog\_color ( FL\_COLOR col1, FL\_COLOR col2 ) \\
\end{tabbing}\end{quote}
}}

To set the background color of the dialog:
%
{\ttfamily{
\begin{quote}\begin{tabbing}
    flx\_set\_dialog\_bgcolor ( FL\_COLOR bg\_color ) \\
\end{tabbing}\end{quote}
}}

To set the dialog font style and size:
%
{\ttfamily{
\begin{quote}\begin{tabbing}
    flx\_set\_dialog\_font ( int lstyle, int lsize ) \\
\end{tabbing}\end{quote}
}}


\subsection{flx\_show\_input}

This routine is similar to \code{flx\_show\_dialog}, but is used to obtain
input from the user.  It is an alternative to \code{fl\_show\_input}.

To invoke an \code{flx\_show\_input}, use the following function:
%
{\ttfamily{
\begin{quote}\begin{tabbing}
     char *flx\_show\_input ( \= int key, \\
                              \> const char *message, \\
                              \> const char *initial )
\end{tabbing}\end{quote}
}}
%
The function returns a pointer to the input string.
{\ttfamily key} is an integer denoting one of the xforms input types
(\code{FL\_NORMAL\_INPUT, FL\_INT\_INPUT}, etc),
{\ttfamily text} is a pointer to the text that
should appear in the dialog, which may have embedded newline characters, and
{\ttfamily initial} is a pointer to the text that should appear as the initial
value in the input box.   Set {\ttfamily initial} to \code{NULL} if you do
not want the initial value set.
To set attributes of the dialog, use the \code{flx\_set\_dialog...} routines
described above before the call to \code{flx\_show\_input}.


% % % % % % % % % % % % % % % % % % % % % % % % % % % % % % % % % % % % % % % %
%
\newpage
\section{Utilities}

\hrule
\vspace{0.5cm}


\subsection{flx\_scale\_form}

\code{flx\_scale\_form} is a simple utility used to scale a form based
on the size of the current font.  This routine will enable your form to look
reasonable on machines that use different default font sizes. A reference scale
factor  of width = 1.0, height = 1.0 is used, based on the size of a 75 dpi
font.   The dimension of a test string is computed, and compared to the
dimension of that string when using a 75 dpi font.  The scale factor is
approximated based on the ratio of the two string dimensions.  After building a
toplevel form, set its scale with the following function:
%
{\ttfamily{
\begin{quote}\begin{tabbing}
     void flx\_scale\_form ( \= FL\_FORM *form )
\end{tabbing}\end{quote}
}}
%
where {\ttfamily form} is a pointer to the new form.  Typically, this would
be called just before {\ttfamily fl\_show\_form}.


\subsection{flx\_sort\_browser}

\code{flx\_sort\_browser} sorts an xforms browser object.  The browser contents
are replaced with the sorted contents.   To sort a browser object, use
%
{\ttfamily{
\begin{quote}\begin{tabbing}
     void flx\_sort\_browser ( \= FL\_OBJECT *browser, \\
                               \> int (*sorter) (const void *, const void *)) \\
\end{tabbing}\end{quote}
}}
%
The contents of the browser are sorted in ascending order according to a
comparison function pointed to  by  \code{sorter()}, which  is  called  with
two  arguments  that point to the objects being compared.  If \code{sorter()}
is \code{NULL}, the browser is sorted alphabetically.  The actual sorting work
is performed by the c library function \code{qsort()}.  See the \code{qsort()}
man page for details on how to write your own comparison function.


\subsection{flx\_justify\_input}

\code{flx\_justify\_input} justifies the string in an input widget so that the
right end of the string as aligned with the right edge of the input box.
If the input widget is wider than the string width, this routine has no effect.
To justify the input string, use
%
{\ttfamily{
\begin{quote}\begin{tabbing}
     void flx\_justify\_input ( \= FL\_OBJECT *inputObj, \\
                                \> char *string, \\
			        \> int style, \\
			        \> int size ) \\
\end{tabbing}\end{quote}
}}
%
The \code{FL\_OBJECT} pointer denotes the input widget.  \code{string} is the
string drawn in the input box, and \code{style} and \code{size} are  the xforms
macros for the font style and size (\code{FL\_NORMAL\_STYLE},
\code{FL\_NORMAL\_SIZE}, etc). This routine is meant to be called immediately
after \code{fl\_set\_input}.


% % % % % % % % % % % % % % % % % % % % % % % % % % % % % % % % % % % % % % % %
%
\newpage
\section{Appendix}

\hrule
\vspace{0.5cm}


\subsection{Object Class Numbers}

The xforms library requires a unique identifer for each added object
class.  These numbers must be in the range of 1001 to 4999.
The \flx library begins class numbers at 3501.
The following object class numbers are currently used:

\begin{enumerate}
      \setlength{\itemsep}{0pt} \setlength{\parsep}{0pt}
      \item[] FLX\_RETURN\_BUTTON    3501
\end{enumerate}

%\begin{enumerate}
%      \setlength{\itemsep}{0pt} \setlength{\parsep}{0pt}
%      \item wingspan/setup\_vms
%      \item wingspan/setup\_sun
%      \item wingspan/setup\_irix
%\end{enumerate}

%
%\begin{figure}[!hbt]
%\begin{center}
%      \epsfxsize=5in
%      \leavevmode\epsffile{banner.ps}
%      \nobreak
%      \caption{
%      WINGSPAN Startup Banner
%      }
%      \vspace{0.35in}
%      \label{fig:banner}
%\end{center}
%\end{figure}
%


\end{document}