path: root/specs/Xtk.intr.front

.\" MIT header page and copyright notice
.\" MIT page header and footers
.\"
.EH ''''
.OH ''''
.EF ''''
.OF ''''
.ps 11
.nr PS 11
\&
.sp 8
.ce 4
\s+2\fB\*(xT\fP\s-2

\s+1\fBX Window System\fP\s-1

\s+1\fBX Version 11, Release \*(Rn\fP\s-1


First Revision - April, 1994
.sp 5
.ce 4
\s-1Joel McCormack
.sp 6p
Digital Equipment Corporation
Western Software Laboratory
.sp 2
.ce 4
Paul Asente
.sp 6p
Digital Equipment Corporation
Western Software Laboratory
.sp 2
.ce 4
Ralph R. Swick
.sp 6p
Digital Equipment Corporation
External Research Group
MIT X Consortium
.sp 2
.ce 3
version 6 edited by Donna Converse
.sp 6p
X Consortium, Inc.\s+1
.bp
\&
.ps 9
.nr PS 9
.sp 8
.LP
X Window System is a trademark of X Consortium, Inc.
.LP
Copyright \(co 1985, 1986, 1987, 1988, 1991, 1994
X Consortium
.LP
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:
.LP
The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.
.LP
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.
.LP
Except as contained in this notice, the name of the X Consortium shall
not be used in advertising or otherwise to promote the sale, use or
other dealings in this Software without prior written authorization
from the X Consortium.
.LP
Copyright \(co 1985, 1986, 1987, 1988, 1991, 1994
Digital Equipment Corporation, Maynard, Massachusetts.
.LP
Permission to use, copy, modify and distribute this documentation for any
purpose and without fee is hereby granted, provided that the above copyright
notice appears in all copies and that both that copyright notice and this
permission notice appear in supporting documentation, and that the name of
Digital not be used in in advertising or publicity pertaining
to distribution of the software without specific, written prior permission.
Digital makes no representations about the suitability of the
software described herein for any purpose.
It is provided ``as is'' without express or implied warranty.
.ps 11
.nr PS 11
.bp 11
.EF ''\fB \\\\n(PN \fP''
.OF ''\fB \\\\n(PN \fP''
.af PN i
.XS ix
Acknowledgments
.XE
\&
.sp 1
.ce 3
\s+1\fBAcknowledgments\fP\s-1
.sp 2
.na
.LP
The design of the X11 Intrinsics was done primarily
by Joel McCormack of Digital WSL.
Major contributions to the design and implementation also
were done by Charles Haynes, Mike Chow, and Paul Asente of Digital WSL.
Additional contributors to the design and/or implementation were:
.LP
.Ds
.ta 3i
Loretta Guarino-Reid (Digital WSL)	Rich Hyde (Digital WSL)
Susan Angebranndt (Digital WSL)	Terry Weissman (Digital WSL)
Mary Larson (Digital UEG)	Mark Manasse (Digital SRC)
Jim Gettys  (Digital SRC)	Leo Treggiari  (Digital SDT)
Ralph Swick (Project Athena and Digital ERP)	Mark Ackerman (Project Athena)
Ron Newman (Project Athena)	Bob Scheifler (MIT LCS)
.De
.LP
The contributors to the X10 toolkit also deserve mention.
Although the X11 Intrinsics present an entirely different programming style,
they borrow heavily from the implicit and explicit concepts in the X10
toolkit.
.LP
The design and implementation of the X10 Intrinsics were done by:
.LP
.Ds
Terry Weissman (Digital WSL)
Smokey Wallace (Digital WSL)
Phil Karlton (Digital WSL)
Charles Haynes (Digital WSL)
Frank Hall (HP)
.De
.LP
The design and implementation of the X10 toolkit's sample widgets were
by the above, as well as by:
.LP
.Ds
Ram Rao (Digital UEG)
Mary Larson (Digital UEG)
Mike Gancarz (Digital UEG)
Kathleen Langone  (Digital UEG)
.De
These widgets provided a checklist of requirements that we
had to address in the X11 Intrinsics.
.LP
Thanks go to Al Mento of Digital's UEG Documentation Group for
formatting and generally improving this document
and to John Ousterhout of Berkeley for extensively reviewing
early drafts of it.
.LP
Finally, a special thanks to Mike Chow,
whose extensive performance analysis of the X10 toolkit provided
the justification to redesign it entirely for X11.
.LP
.sp
.Ds 0
Joel McCormack
Western Software Laboratory
Digital Equipment Corporation

March 1988
.De
.bp
.LP
The current design of the \*(xI has benefited greatly from the
input of several dedicated reviewers in the membership of the
X Consortium.
In addition to those already mentioned,
the following individuals have dedicated significant time
to suggesting improvements to the \*(xI:
.LP
.Ds
.ta 3i
Steve Pitschke (Stellar)	C. Doug Blewett (AT&T)
Bob Miller (HP)	David Schiferl (Tektronix)
Fred Taft (HP)	Michael Squires (Sequent)
Marcel Meth (AT&T)	Jim Fulton (MIT)
Mike Collins (Digital)	Kerry Kimbrough (Texas Instruments)
Scott McGregor (Digital)	Phil Karlton (Digital)
Julian Payne (ESS)	Jacques Davy (Bull)
Gabriel Beged-Dov (HP)	Glenn Widener (Tektronix)
.De
.LP
Thanks go to each of them for the countless hours spent
reviewing drafts and code.
.LP
.sp
.Ds 0
Ralph R. Swick
External Research Group
Digital Equipment Corporation
MIT Project Athena

June 1988
.De
.sp
.LP
From Release 3 to Release 4, several new members joined the design
team.  We greatly appreciate the thoughtful comments, suggestions,
lengthy discussions, and in some cases implementation code contributed by each
of the following:
.LP
.Ds
.ta 3i
Don Alecci (AT&T)	Ellis Cohen (OSF)
Donna Converse (MIT)	Clive Feather (IXI)
Nayeem Islam (Sun)	Dana Laursen (HP)
Keith Packard (MIT)	Chris Peterson (MIT)
Richard Probst (Sun)	Larry Cable (Sun)
.De
.sp
.LP
In Release 5, the effort to define the internationalization additions was
headed by Bill McMahon of Hewlett Packard and Frank Rojas of IBM.  This
has been an educational process for many of us, and Bill and Frank's
tutelage has carried us through.  Vania Joloboff of the OSF also contributed
to the internationalization additions.  The implementation efforts of
Bill, Gabe Beged-Dov, and especially Donna Converse for this release
are also gratefully acknowledged.
.sp
.Ds 0
Ralph R. Swick

December 1989
and
July 1991
.De
.bp
.LP
The Release 6 Intrinsics is a result of the collaborative
efforts of participants in the X Consortium's \fBintrinsics\fP
working group.
A few individuals contributed substantial design proposals,
participated in lengthy discussions, reviewed final specifications,
and in most cases, were also responsible for sections of the implementation.
They deserve recognition and thanks for their major contributions:
.LP
.Ds
.ta 3i
Paul Asente (Adobe)		Larry Cable (SunSoft)
Ellis Cohen (OSF)		Daniel Dardailler (OSF)
Vania Joloboff (OSF)		Kaleb Keithley (X Consortium)
Courtney Loomis (HP)		Douglas Rand (OSF)
Bob Scheifler (X Consortium)	Ajay Vohra (SunSoft)
.De
.LP
Many others analyzed designs, offered useful comments and suggestions,
and participated in a significant subset of the process.
The following people deserve thanks for their contributions:
Andy Bovingdon, Sam Chang, Chris Craig,
George Erwin-Grotsky, Keith Edwards, Clive Feather, Stephen Gildea,
Dan Heller, Steve Humphrey, David Kaelbling,
Jaime Lau, Rob Lembree, Stuart Marks, Beth Mynatt,
Tom Paquin, Chris Peterson, Kamesh Ramakrishna, Tom Rodriguez,
Jim VanGilder, Will Walker, and Mike Wexler.
.LP
I am especially grateful to two of my colleagues: Ralph Swick for
expert editorial guidance, and Kaleb Keithley for leadership in
the implementation and the specification work.
.sp
.Ds 0
Donna Converse
X Consortium
April 1994
.De
.bp
.XS xii
About This Manual
.XE
\&
.sp 1
.ce 3
\s+1\fBAbout This Manual\fP\s-1
.sp 2
.na
.LP
\fI\*(xT\fP is intended to be read by both application programmers who will
use one or more of the many widget sets built with the \*(xI
and by widget programmers who will use the \*(xI to build widgets
for one of the widget sets.
Not all the information in this manual, however, applies to both audiences.
That is, because the application programmer is likely to use only a number of
the \*(xI functions in writing an application and because the widget programmer
is likely to use many more, if not all, of the \*(xI functions in building
a widget,
an attempt has been made to highlight those areas of information that are
deemed to be of special interest for the application programmer.
(It is assumed the widget programmer will have to be familiar with all
the information.)
Therefore, all entries in the table of contents that are printed in \fBbold\fP
indicate the information that should be of special interest to an
application programmer.
.LP
It is also assumed that, as application programmers become
more familiar with the concepts discussed in this manual,
they will find it more convenient to implement
portions of their applications as special-purpose or custom widgets.
It is possible, nonetheless, to use widgets without knowing how to build them.
.SH
Conventions Used in this Manual
.LP
This document uses the following conventions:
.IP \(bu 5
Global symbols are printed in
.PN this
.PN special
.PN font .
These can be either function names,
symbols defined in include files, data types, or structure names.
Arguments to functions, procedures, or macros are printed in \fIitalics\fP.
.IP \(bu 5
Each function is introduced by a general discussion that
distinguishes it from other functions.
The function declaration itself follows,
and each argument is specifically explained.
General discussion of the function, if any is required,
follows the arguments.
.IP \(bu 5
To eliminate any ambiguity between those arguments that you pass and those that
a function returns to you,
the explanations for all arguments that you pass start with the word
\fIspecifies\fP or, in the case of multiple arguments, the word \fIspecify\fP.
The explanations for all arguments that are returned to you start with the
word \fIreturns\fP or, in the case of multiple arguments, the word \fIreturn\^\fP.
.bp 1
.af PN 1
.EH '\fBX Toolkit Intrinsics\fP''\fBX11 Release \*(Rn\fP'
.OH '\fBX Toolkit Intrinsics\fP''\fBX11 Release \*(Rn\fP'