XForms Online Manual
Keywords: forms

Next: List of Figures

Forms Library
A Graphical User Interface Toolkit for X
V0.88 November 1997

T. C. Zhao
Department of Physics, University of Wisconsin-Milwaukee
Milwaukee, WI 53201, USA
and
Mark Overmars
Department of Computer Science, Utrecht University
P.O.Box 80.089, 3508 TB Utrecht, the Netherlands

Copyright (©) 1996,1997 by T.C. Zhao and Mark Overmars
All rights reserved.
No part of this document may be reproduced, in any form or by any means, without permission from the authors. Permission to produce hardcopies in its entirety for private use is granted.

# Preface

Window-based user interfaces are becoming a common and required feature for most computer systems, and as a result, users have come to expect all applications to have polished user-friendly interfaces. Unfortunately, constructing user interfaces for programs is in general a time consuming process. In the last few years a number of packages have appeared that help build up graphical user interfaces (so-called GUI's) in a simple way. Most of them, though, are difficult to use and/or expensive to buy and/or limited in their capabilities. The Forms Library was constructed to remedy this problem. The design goals when making the Forms Library were to create a package that is intuitive, simple to use, powerful, graphically good looking and easily extendible.

The main notion in the Forms Library is that of a form. A form is a window on which different objects are placed. Such a form is displayed and the user can interact with the different objects on the form to indicate his/her wishes. Many different classes of objects exist, like buttons (of many different flavors) that the user can push with the mouse, sliders with which the user can indicate a particular setting, input fields in which the user can provide textual input, menus from which the user can make choices, browsers in which the user can scroll through large amounts of text (e.g. help files), etc. Whenever the user changes the state of a particular object on one of the forms displayed the application program is notified and can take action accordingly. There are a number of different ways in which the application program can interact with the forms, ranging from very direct (waiting until something happens) to the use of callback routines that are called whenever an object changes state.

The application program has a large amount of control over how objects are drawn on the forms. It can set color, shape, text style, text size, text color, etc. In this way forms can be fine tuned to one's liking.

The Forms Library consists of a large number of C-routines to build up interaction forms with buttons, sliders, input fields, dials, etc. in a simple way. The routines can be used both in C and in C++ programs. The library uses only the services provided by the Xlib and should run on all workstations that have X installed on them. The current version needs 4bits of color (or grayscale) to look nice, but it will function properly on workstations having less depth (e.g., XForms works on B&W X-terminals).

The library is easy to use. Defining a form takes a few lines of code and interaction is fully handled by the library routines. A number of demo programs are provided to show how easy forms are built and used. For simple forms and those that may be frequently used in application programs, e.g., to ask a question or select a file name, special routines are provided. For example, to let the user choose a file in a graphical way (allowing him/her to walk through the directory hierarchy with a few mouse clicks) the application program needs to use just one line of code.

To make designing forms even easier a Form Designer is provided. This is a program that lets you interactively design forms and generate the corresponding C-code. You simply choose the objects you want to place on the forms from a list and draw them on a form. Next you can set attributes, change size and position of the objects, etc., all using the mouse.

Although this document describes all you need to know about using the Forms Library for X, it is not an X tutorial. On the contrary, details of programming in X are purposely hidden in the Forms Library interfaces, and one need not be an X-expert to use the Forms Library, although some knowledge of how X works would help to understand the inner workings of the Forms Library.

Forms Library and all the programs either described in this document or distributed as demos have been tested under X11 R4, R5 & R6 on all major UNIX platforms, including SGI, SUN, HP, IBM RS6000/AIX, Dec Alpha/OSF1, Linux(i386, alpha, m68k and sparc) as well as FreeBSD, NetBSD (i386, m68k and sparc), OpenBSD(i386, pmax, sparc), SCO and Unixware. Due to access and knowledge, testing on non-unix platforms such as OpenVMS and OS/2 are less than comprehensive.

This document consists of four parts. The first part is a tutorial that provides an easy, informal introduction to the Forms Library. This part should be read by everybody that wants to use the library. You are encouraged to try variations of the demo programs distributed in the Forms Library package.

Part ii describes the Form Designer with which you can design forms interactively and have Form Designer write code for you.

Part iii gives an overview of all object classes currently available in the library. The tutorial part only mentions the most basic classes but here you find a complete overview.

Adding new object classes to the system is not very complicated. Part iv describes how this should be done.

## Version Note

The authors request that the following name(s) be used when referring to this toolkit

Forms Library for X
Forms Library
or simply
XForms

Forms Library is 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 (`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.

This software is provided ``as is'' without warranty of any kind, either expressed or implied. The entire risk as to the quality and performance of the software is with you. Should the software prove defective, you assume the cost of all necessary servicing, repair or correction and under no circumstance shall the authors be liable for any damages resulting from the use or mis-use of this software.

The development environment for xforms is Linux 1.0.8/a.out X11R5 with additional testing and validation on SGI R8000 and occasionally IBM RS6000/AIX and other machines. For every public release, most of the demos and some internal testing programs are run on each platform to ensure quality of the distribution.

Figures in this document were produced by `fd2ps`, a program that takes the output of the form designer and converts the form definition into an encapsulated POSTSCRIPT file. `fd2ps` as of XForms V0.85 is included in the distribution.

This document is dated November 16, 1997 .

## Support

Although XForms has gone through extensive testing, there are most likely a number of bugs remaining. Your comments would be greatly appreciated. Please send any bug reports or suggestions to T.C. Zhao (`zhao@bragg.phys.uwm.edu` or `zhao@bloch.phys.uwm.edu` but not both). Please do not expect an immediate response, but we do appreciate your input and will do our best.

## Bindings to other languages

As of this writing, the authors are aware of the following bindings

perl
  binding by Martin Bartlett (`martin@nitram.demon.co.uk`),
ada95
  binding by G. Vincent Castellano (`gvc@ocsystems.com`),
Fortran
  binding by G. Groten (`zdv017@zam212.zam.kfa-juelich.de`) and Anke Haeming (`A.Haeming@kfa-juelich.de`)
pascal
  binding by Michael Van Canneyt (`michael@tfdec1.fys.kuleuven.ac.be`)
python
  binding by Roberto Alsina (`ralsina@ultra7.unl.edu.ar`). (Seems the author has stopped working on this binding).

Follow the links on XForms's home page to get more info on these bindings.

### Archive Sites

Permanent home for the Forms Library is at

       ftp://einstein.phys.uwm.edu/pub/xforms
       ftp://ftp.cs.ruu.nl/pub/XFORMS  (Primary mirror site)

The primary site is mirrored by many sites around the world. The following are some of the mirror sites

       ftp://ftp.fu-berlin.de/unix/X11/gui/xforms
       ftp://ftp.st.ryukoku.ac.jp/pub/X11/xforms
       ftp://ftp.via.ecp.fr/pub2/xforms
       ftp://ftp.unipi.it/pub/mirror/xforms
       ftp://ftp.uni-trier.de/pub/unix/X11/xforms

Additional mirrors, html version of this document, news and other information related to XForms can be accessed through www via the following URL

       http://bragg.phys.uwm.edu/xforms
       http://bloch.phys.uwm.edu/xforms   (mirror)

In addition to ftp and www server, a mail server is available for those who do not have direct internet access.

To use the mail server, send a message to `mail-server@cs.ruu.nl` or the old-fashioned path alternative `uunet!mcsun!sun4nl!ruuinf!mail-server`.

The message should be something like the following

       begin
       path fred@stone.age.edu  (substitute your address)
       send help
       end

To get a complete listing of the archive tree, issue `send ls-lR.Z`.

### Mailing List

A mailing list for news and discussions about XForms is available. To subscribe or un-subscribe, send a message to `xforms-request@bob.usuf2.usuhs.mil` with one of the following commands as the mail body

       help
       subscribe
       unsubscribe

To use the mailing list, send mail to `xforms@bob.usuf2.usuhs.mil`. Please remember that the message will be sent to hundreds of people. Please Do not send subscribe/unsubscribe messages to the mailing list, send them to `xforms-request@bob.usuf2.usuhs.mil`.

The mailing list archive is at `http://bob.usuf2.usuhs.mil/mailserv/list-archives`.

## Thanks

A large number of people contributed one way or another to the development of Forms Library, without whose testing, bug reports and suggestions, Forms Library would not be what it is today and would certainly not be in the relatively bug free state it is in now. We thank Steve Lamont of UCSD (`spl@szechuan.ucsd.edu`), for his numerous suggestions and voluminous contributions to the mailing list. We thank Erik Van Riper (`geek@midway.com`), formerly of CUNY, and Robert Williams of USUHS (`bob@bob.usuf2.usuhs.mil`) for running the mailing list and keeping it running smoothly. We also thank every participant on the mailing list who contributed by asking questions and challenging our notion of what typical use of the Forms Library is. The html version of the document, undoubtedly browsed by the thousands, is courtesy of Danny Uy (`dau@westworld.com`). We appreciate the accurate and detailed bug reports, almost always accompanied with a demo program, from Gennady Sorokopud (`gena@NetVision.net.il`) and Rouben Rostamian (`rostamian@umbc.edu`). We also thank Martin Bartlett (`martin@nitram.demon.co.uk`), who, in addition to marrying Forms Library to `perl`, made several xforms API suggestions, Last but certainly not least, we thank Henrik Klagges (`henrik@UniX11.com`) for his numerous suggestions during the early stages of the development.

Currently GE Medical Systems, P.O. Box 414, NB-922, Milwaukee, WI 53201-0414

- List of Figures
- Contents
- Using the Forms Library
- The Form Designer
- An overview of all object classes
- Designing your own object classes
- Appendices
- Index

Next: List of Figures