-- -- XToolkit Intrinsics — C Language Interface XWindowSystem XVersion 11, Release 6.4 First Revision - April, 1994 Joel McCormack Digital Equipment Corporation Western Software Laboratory Paul Asente Digital Equipment Corporation Western Software Laboratory Ralph R. Swick Digital Equipment Corporation External Research Group MIT X Consortium version 6 edited by Donna Converse XConsortium, Inc. -- -- XWindowSystem is a trademark of X Consortium, Inc. Copyright © 1985, 1986, 1987, 1988, 1991, 1994 X Consortium Permission is hereby granted, free of charge, to anyperson obtaining a copyofthis software and associated documenta- tion 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: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Soft- ware. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOTLIMITED TOTHE WARRANTIES OF MERCHANTABILITY,FITNESS FOR A PARTIC- ULAR PURPOSE AND NONINFRINGEMENT.INNOEVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,WHETHER IN AN ACTION OF CONTRACT,TORTOROTH- ERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. Except as contained in this notice, the name of the X Consortium shall not be used in advertising or otherwise to pro- mote the sale, use or other dealings in this Software without prior written authorization from the X Consortium. Copyright © 1985, 1986, 1987, 1988, 1991, 1994 Digital Equipment Corporation, Maynard, Massachusetts. Permission to use, copy, modify and distribute this documentation for anypurpose 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 per- taining to distribution of the software without specific, written prior permission. Digital makes no representations about the suitability of the software described herein for anypurpose. It is provided ‘‘as is’’without express or implied warranty. -- -- Acknowledgments 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, MikeChow, and Paul Asente of Digital WSL. Additional contributors to the design and/or implementation were: 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) The contributors to the X10 toolkit also deservemention. Although the X11 Intrinsics present an entirely different programming style, theyborrowheavily from the implicit and explicit concepts in the X10 toolkit. The design and implementation of the X10 Intrinsics were done by: Terry Weissman (Digital WSL) Smokey Wallace (Digital WSL) Phil Karlton (Digital WSL) Charles Haynes (Digital WSL) Frank Hall (HP) The design and implementation of the X10 toolkit’ssample widgets were by the above,aswell as by: Ram Rao (Digital UEG) Mary Larson (Digital UEG) MikeGancarz (Digital UEG) Kathleen Langone (Digital UEG) These widgets provided a checklist of requirements that we had to address in the X11 Intrinsics. Thanks go to Al Mento of Digital’sUEG Documentation Group for formatting and generally improving this document and to John Ousterhout of Berkeleyfor extensively reviewing early drafts of it. Finally,aspecial thanks to MikeChow, whose extensive performance analysis of the X10 toolkit provided the justification to redesign it entirely for X11. Joel McCormack Western Software Laboratory Digital Equipment Corporation March 1988 xi -- -- The current design of the Intrinsics 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 Intrin- sics: 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) MikeCollins (Digital) Kerry Kimbrough (Texas Instruments) Scott McGregor (Digital) Phil Karlton (Digital) Julian Payne (ESS) Jacques Davy (Bull) Gabriel Beged-Dov(HP) Glenn Widener (Tektronix) Thanks go to each of them for the countless hours spent reviewing drafts and code. Ralph R. Swick External Research Group Digital Equipment Corporation MIT Project Athena June 1988 From Release 3 to Release 4, several newmembers joined the design team. We greatly appreciate the thoughtful comments, suggestions, lengthydiscussions, and in some cases implementation code contributed by each of the following: 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) 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 manyof us, and Bill and Frank’stutelage has carried us through. Vania Joloboffofthe OSF also con- tributed to the internationalization additions. The implementation efforts of Bill, Gabe Beged- Dov, and especially Donna Converse for this release are also gratefully acknowledged. Ralph R. Swick December 1989 and July 1991 xii -- -- The Release 6 Intrinsics is a result of the collaborative efforts of participants in the X Consor- tium’s intrinsics working group. Afew individuals contributed substantial design proposals, par- ticipated in lengthydiscussions, reviewed final specifications, and in most cases, were also responsible for sections of the implementation. Theydeserverecognition and thanks for their major contributions: Paul Asente (Adobe) Larry Cable (SunSoft) Ellis Cohen (OSF) Daniel Dardailler (OSF) Vania Joloboff(OSF) Kaleb Keithley(XConsortium) CourtneyLoomis (HP) Douglas Rand (OSF) Bob Scheifler (X Consortium) Ajay Vohra (SunSoft) Manyothers analyzed designs, offered useful comments and suggestions, and participated in a significant subset of the process. The following people deservethanks 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 Lem- bree, Stuart Marks, Beth Mynatt, Tom Paquin, Chris Peterson, Kamesh Ramakrishna, Tom Rodriguez, Jim VanGilder,Will Walker,and MikeWexler. Iamespecially grateful to twoofmycolleagues: Ralph Swick for expert editorial guidance, and Kaleb Keithleyfor leadership in the implementation and the specification work. Donna Converse XConsortium April 1994 xiii -- -- About This Manual XToolkit Intrinsics — C Language Interface is intended to be read by both application program- mers who will use one or more of the manywidget sets built with the Intrinsics and by widget programmers who will use the Intrinsics 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 Intrinsics functions in writing an application and because the widget programmer is likely to use manymore, if not all, of the Intrinsics 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 pro- grammer will have tobefamiliar with all the information.) Therefore, all entries in the table of contents that are printed in bold indicate the information that should be of special interest to an application programmer. It is also assumed that, as application programmers become more familiar with the concepts dis- cussed in this manual, theywill find it more convenient to implement portions of their applica- tions as special-purpose or custom widgets. It is possible, nonetheless, to use widgets without knowing howtobuild them. Conventions Used in this Manual This document uses the following conventions: •Global symbols are printed in this special font.These can be either function names, sym- bols defined in include files, data types, or structure names. Arguments to functions, proce- dures, or macros are printed in italics. •Each function is introduced by a general discussion that distinguishes it from other func- tions. The function declaration itself follows, and each argument is specifically explained. General discussion of the function, if anyisrequired, follows the arguments. •Toeliminate anyambiguity between those arguments that you pass and those that a func- tion returns to you, the explanations for all arguments that you pass start with the word specifies or,inthe case of multiple arguments, the word specify.The explanations for all arguments that are returned to you start with the word returns or,inthe case of multiple arguments, the word