COPYING | 37 + Makefile.am | 2 configure.ac | 42 +- man/Makefile.am | 2 spec/AsciiSink | 77 +++ spec/AsciiSource | 208 +++++++++ spec/AsciiText | 166 +++++++ spec/Box | 139 ++++++ spec/CH1 | 411 +++++++++++++++++++ spec/CH2 | 1103 +++++++++++++++++++++++++++++++++++++++++++++++++++++ spec/CH3.intro | 67 +++ spec/CH4.intro | 87 ++++ spec/CH5.intro | 292 ++++++++++++++ spec/CH6.intro | 84 ++++ spec/CH7.intro | 99 ++++ spec/Command | 205 +++++++++ spec/Dialog | 280 +++++++++++++ spec/Form | 200 +++++++++ spec/Grip | 157 +++++++ spec/Label | 122 +++++ spec/List | 341 ++++++++++++++++ spec/Makefile.am | 96 ++++ spec/MenuButton | 215 ++++++++++ spec/Paned | 492 +++++++++++++++++++++++ spec/Panner | 247 +++++++++++ spec/Porthole | 125 ++++++ spec/Repeater | 184 ++++++++ spec/Scrollbar | 386 ++++++++++++++++++ spec/Simple | 95 ++++ spec/SimpleMenu | 315 +++++++++++++++ spec/Sme | 106 +++++ spec/SmeBSB | 125 ++++++ spec/SmeLine | 72 +++ spec/StripChart | 160 +++++++ spec/TPage_Credits | 156 +++++++ spec/Template | 426 ++++++++++++++++++++ spec/Text | 123 +++++ spec/TextActions | 506 ++++++++++++++++++++++++ spec/TextCustom | 63 +++ spec/TextFuncs | 397 +++++++++++++++++++ spec/TextSink | 420 ++++++++++++++++++++ spec/TextSource | 331 +++++++++++++++ spec/Toggle | 370 +++++++++++++++++ spec/Tree | 181 ++++++++ spec/Viewport | 156 +++++++ spec/block.awk | 22 + spec/fixindex.awk | 73 +++ spec/indexmacros.t | 42 ++ spec/macros.t | 226 ++++++++++ spec/strings.mit | 10 spec/strings.xaw | 714 ++++++++++++++++++++++++++++++++++ spec/widg.idxmac.t | 3 src/Makefile.am | 1 src/Tip.c | 1 54 files changed, 10946 insertions(+), 14 deletions(-)
New commits: commit 4ec346977273cc217b22a9225cb0d90351e6069c Author: Alan Coopersmith <alan.coopersm...@sun.com> Date: Sat Oct 17 14:45:39 2009 -0700 libXaw 1.0.7 Signed-off-by: Alan Coopersmith <alan.coopersm...@sun.com> diff --git a/configure.ac b/configure.ac index c1f4f63..bd7b202 100644 --- a/configure.ac +++ b/configure.ac @@ -3,7 +3,7 @@ dnl Process this file with autoconf to create configure. AC_PREREQ([2.57]) AC_INIT([libXaw], - 1.0.6, + 1.0.7, [https://bugs.freedesktop.org/enter_bug.cgi?product=xorg], libXaw) commit d158018aad18552c5788df38de40ef50b7652dde Author: Alan Coopersmith <alan.coopersm...@sun.com> Date: Fri Oct 9 16:14:59 2009 -0700 Move Xaw specification document from xorg-docs module to spec/* Makefile support added to build postscript, text & html output, and install it to ${docdir}, if groff is found and --disable-docs was not specified Signed-off-by: Alan Coopersmith <alan.coopersm...@sun.com> diff --git a/COPYING b/COPYING index 19233ef..dcbab5e 100644 --- a/COPYING +++ b/COPYING @@ -130,3 +130,40 @@ not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization from said copyright holders. + + +Copyright 1985, 1986, 1987, 1988, 1989, 1991, 1994 X Consortium + +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: + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + +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. + +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. + +Copyright 1985, 1986, 1987, 1988, 1989, 1991 +Digital Equipment Corporation, Maynard, Massachusetts. + +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. diff --git a/Makefile.am b/Makefile.am index 2e3f9c2..16951fe 100644 --- a/Makefile.am +++ b/Makefile.am @@ -1,4 +1,4 @@ -SUBDIRS = include src man +SUBDIRS = include src man spec pkgconfigdir = $(libdir)/pkgconfig pkgconfig_DATA = diff --git a/configure.ac b/configure.ac index 024e6ba..c1f4f63 100644 --- a/configure.ac +++ b/configure.ac @@ -19,6 +19,29 @@ XORG_MACROS_VERSION(1.3) # Check for progs AC_PROG_CC AC_PROG_LIBTOOL +AC_PROG_AWK +AC_PROG_SED + +AC_PATH_PROGS([GROFF], [groff], [none], [$PATH:/usr/gnu/bin]) + +AC_MSG_CHECKING([whether to build documentation]) +AC_ARG_ENABLE(docs, AC_HELP_STRING([--enable-docs], + [Enable building of Xaw documentation]), + [build_docs="${enableval}"], [build_docs="auto"]) + +if test "x${build_docs}" = xauto; then + if test "x${GROFF}" = xnone ; then + build_docs=no + else + build_docs=yes + fi +fi +AC_MSG_RESULT([${build_docs}]) +if test "x${build_docs}" = xyes && test "x${GROFF}" = xnone ; then + AC_MSG_ERROR([can't build documentation without groff]) +fi + +AM_CONDITIONAL(BUILD_DOCS, [test x$build_docs = xyes]) # Need to call this explicitly since the first call to PKG_CHECK_MODULES # is in an if statement, and later calls would break if it's skipped. @@ -29,7 +52,6 @@ XORG_DEFAULT_OPTIONS # # fix libtool to set SONAME to libXaw.so.$major # -AC_PROG_SED AC_CONFIG_COMMANDS([libtool_hack], [ cp -f libtool libtool_ test -z "$SED" && SED=sed @@ -106,6 +128,7 @@ AC_CHECK_FUNCS([iswalnum]) AC_OUTPUT([Makefile include/Makefile man/Makefile + spec/Makefile src/Makefile]) if test "x$build_v6" = xyes; then diff --git a/spec/AsciiSink b/spec/AsciiSink new file mode 100644 index 0000000..56dc20e --- /dev/null +++ b/spec/AsciiSink @@ -0,0 +1,77 @@ +.\" $Xorg: AsciiSink,v 1.3 2000/08/17 19:42:25 cpqbld Exp $ +.LP +.NH 2 +Ascii Sink Object and Multi Sink Object +.LP +.XS + AsciiSink Object +.XE +.IN "AsciiSink object" "" "@DEF@" +.LP +.Ds 0 +.TA 2.0i +.ta 2.0i +Application Header file <X11/Xaw/AsciiSink.h> +.IN "AsciiSink.h" "" +Class Header file <X11/Xaw/AsciiSinkP.h> +.IN "AsciiSinkP.h" "" +Class asciiSinkObjectClass +.IN "asciiSinkObjectClass" "" +Class Name AsciiSink +.IN "AsciiSink object" "class name" +Superclass TextSink +.De +.LP +The AsciiSink or MultiSink object is used by a text widget to render the text. +Depending on its \fBinternational\fP resource, a +AsciiText widget will create one or the other of these when the AsciiText +itself is created. Both types are nearly identical; the following discussion +applies to both, with MultiSink differences noted only as they occur. +The AsciiSink +will display all printing characters in an 8 bit font, along with handling Tab +and Carriage Return. The name has been left as ``AsciiSink'' for compatibility. +\fIThe MultiSink will display all printing characters in a font set, along with +handling Tab and Carriage +Return.\fP The source object also reports the text window metrics to the +text widgets. +.NH 3 +Resources +.LP +When creating an AsciiSink object instance, the following resources are +retrieved from the argument list or from the resource database: +.LP +.IN "AsciiSink object" "resources" +.TS H +lw(1i) lw(1i) lw(1i) lw(.5i) lw(2i). +_ +.sp 3p +.TB +Name Class Type Notes Default Value +.sp 3p +_ +.TH +.R +.sp 3p +background Background Pixel XtDefaultBackground +destroyCallback Callback XtCallbackList NULL +displayNonprinting Output Boolean True +echo Output Boolean True +font Font XFontStruct* XtDefaultFont +fontSet FontSet XFontSet XtDefaultFontSet +foreground Foreground Pixel XtDefaultForeground +.sp 3p +_ +.TE +.Bg Bold +This resource is retrieved by the AsciiSink instead of being copied +from the Text widget. +.Dc +.Sd Bold +.Sh Bold +.IP \fBfont\fP 1.5i +The text font to use when displaying the \fBstring\fP. +(This resource is present in the AsciiSink, but not the MultiSink.) +.IP \fBfontSet\fP 1.5i +The text font set to use when displaying the \fBstring\fP. +(This resource is present in the MultiSink, but not the AsciiSink.) + diff --git a/spec/AsciiSource b/spec/AsciiSource new file mode 100644 index 0000000..19b9765 --- /dev/null +++ b/spec/AsciiSource @@ -0,0 +1,208 @@ +.\" $Xorg: AsciiSource,v 1.3 2000/08/17 19:42:26 cpqbld Exp $ +.NH 2 +Ascii Source Object and Multi Source Object +.LP +.XS + AsciiSrc Object +.XE +.IN "AsciiSrc object" "" "@DEF@" +.LP +.Ds 0 +.TA 2.0i +.ta 2.0i +Application Header file <X11/Xaw/AsciiSrc.h> or <X11/Xaw/MultiSrc.h> +.IN "AsciiSrc.h" "" +Class Header file <X11/Xaw/AsciiSrcP.h> or <X11/Xaw/MultiSrcP.h> +.IN "AsciiSrcP.h" "" +Class asciiSrcObjectClass or multiSrcObjectClass +.IN "asciiSrcObjectClass" "" +Class Name AsciiSrc or MultiSrc +.IN "AsciiSrc object" "class name" +Superclass TextSource +.De +.LP +The AsciiSrc or MultiSrc object is used by a text widget to read the text from a +file or string in memory. Depending on its \fBinternational\fP resource, an +AsciiText widget will create one or the other of these when the AsciiText +itself is created. Both types are nearly identical; the following discussion +applies to both, with MultiSrc differences noted only as they occur. +.LP +The AsciiSrc understands all Latin1 characters plus Tab +and Carriage Return. \fIThe MultiSrc understands any set of character sets that +the underlying X implementation's internationalization handles.\fP +.LP +The AsciiSrc can be either of two types: \fBXawAsciiFile\fP +or \fBXawAsciiString\fP. +.LP +AsciiSrc objects of type \fBXawAsciiFile\fP read the text from a file and +store it +into an internal buffer. This buffer may then be modified, provided the +text widget is in the correct edit mode, just as if it were a source of +type \fBXawAsciiString\fP. Unlike R3 and earlier versions of the AsciiSrc, +it is now possible to specify an editable disk source. The file is not +updated, however, until a call to \fBXawAsciiSave\fP is made. When the +source is in this mode the \fBuseStringInPlace\fP resource is ignored. +.LP +AsciiSrc objects of type \fBXawAsciiString\fP have the text buffer +implemented as a string. +\fIMultiSrc objects of type \fBXawAsciiString\fP have the text buffer +implemented as a wide character string.\fP +The string owner is responsible for allocating and managing storage for the +string. +.LP +In the default case for AsciiSrc objects of type \fBXawAsciiString\fP, +the resource \fBuseStringInPlace\fP is false, +and the widget owns the string. The initial value of the +string resource, and any update made by the application +programmer to the string resource with \fBXtSetValues\fP, is copied +into memory private to the widget, and managed internally by the widget. +The application writer +does not need to worry about running out of buffer space +(subject to the total memory available to the application). +The performance does not decay linearly as the buffer grows +large, as is necessarily the case when the text buffer is used +in place. The application writer must use \fBXtGetValues\fP to +determine the contents of the text buffer, which will return +a copy of the widget's text buffer as +it existed at the time of the \fBXtGetValues\fP call. This copy +is not affected by subsequent updates to the text buffer, i.e., +it is not updated as the user types input into the text buffer. +This copy is freed upon the next call to XtGetValues to +retrieve the string resource; however, to conserve memory, +there is a convenience routine, \fBXawAsciiSourceFreeString\fP, allowing the +application programmer to direct the widget to free the copy. +.LP +When the resource \fBuseStringInPlace\fP is true and the AsciiSrc object +is of type \fBXawAsciiString\fP, the application +is the string owner. The widget will take the value +of the string resource as its own text buffer, and the \fBlength\fP +resource indicates the buffer size. In this case +the buffer contents change as the user types at the widget; +it is not necessary to call \fBXtGetValues\fP on the string +resource to determine the contents of the buffer\*-it will +simply return the address of the application's implementation +of the text buffer. +.NH 3 +Resources +.LP +When creating an AsciiSrc object instance, the following resources are +retrieved from the argument list or from the resource database: +.LP +.IN "AsciiSrc object" "resources" +.TS H +lw(1i) lw(1i) lw(1i) lw(.5i) lw(2i). +_ +.sp 3p +.TB +Name Class Type Notes Default Value +.sp 3p +_ +.TH +.R +.sp 3p +callback Callback XtCallbackList NULL +dataCompression DataCompression Boolean True +destroyCallback Callback Callback NULL +editType EditType EditMode XawtextRead +length Length Int A length of \fBstring\fP +pieceSize PieceSize Int BUFSIZ +string String String NULL +type Type AsciiType XawAsciiString +useStringInPlace UseStringInPlace Boolean False +.sp 3p +_ +.TE +.Oc Bold +.Dc +.Od Bold +.Oe +.Ol Bold +.Op Bold +.Os Bold +.Ot Bold +.Ou Bold +.NH 3 +Convenience Routines +.LP +The AsciiSrc has a few convenience routines that allow the +application programmer quicker or easier access to some of the +commonly used functionality of the AsciiSrc. +.NH 4 +Conserving Memory +.LP +When the AsciiSrc widget is not in \fBuseStringInPlace\fP mode +space must be allocated whenever the file is saved, or the string is +requested with a call to \fBXtGetValues\fP. This memory is allocated on the +fly, and remains valid until the next time a string needs to be allocated. +You may save memory by freeing this string as soon as you are done +with it by calling \fBXawAsciiSourceFreeString\fP. +.FD 0 +void XawAsciiSourceFreeString(\fIw\fP) +.IN "XawAsciiSourceFreeString" "" @DEF@ +.br +Widget \fIw\fP; +.FN +.IP \fIw\fP 1i +Specifies the AsciiSrc object. +.LP +This function will free the memory that contains the string pointer returned +by \fBXtGetValues\fP. This will normally happen automatically when +the next call to \fBXtGetValues\fP occurs, or when the widget is destroyed. +.NH 4 +Saving Files +.LP +To save the changes made in the current text source into a file use +\fBXawAsciiSave\fP. +.FD 0 +Boolean XawAsciiSave(\fIw\fP) +.IN "XawAsciiSave" "" @DEF@ +.br +Widget \fIw\fP; +.FN +.IP \fIw\fP 1i +Specifies the AsciiSrc object. +.LP +\fBXawAsciiSave\fP returns \fBTrue\fP if the save was successful. +It will update the file named in the \fBstring\fP resource. +If the buffer has not been changed, no action will be taken. This function +only works on an AsciiSrc of type \fBXawAsciiFile\fP. +.LP +.sp 1 +To save the contents of the current text buffer into a named file use +\fBXawAsciiSaveAsFile\fP. +.FD 0 +Boolean XawAsciiSaveAsFile(\fIw\fP, \fIname\fP) +.IN "XawAsciiSaveAsFile" "" @DEF@ +.br +Widget \fIw\fP; +.br +String \fIname\fP; +.FN +.IP \fIw\fP 1i +Specifies the AsciiSrc object. +.IP \fIname\fP 1i +The name of the file to save the current buffer into. +.LP +This function returns \fBTrue\fP if the save was successful. +\fBXawAsciiSaveAsFile\fP will work with a buffer of either type +\fBXawAsciiString\fP or type \fBXawAsciiFile\fP. +.NH 4 +Seeing if the Source has Changed +.LP +To find out if the text buffer in an AsciiSrc object has changed +since the last time it was saved with \fBXawAsciiSave\fP or queried +.IN "XawAsciiSave" "" +use \fBXawAsciiSourceChanged\fP. +.FD 0 +Boolean XawAsciiSourceChanged(\fIw\fP) +.IN "XawAsciiSourceChanged" "" @DEF@ +.br +Widget \fIw\fP; +.FN +.IP \fIw\fP 1i +Specifies the AsciiSrc object. +.LP +This function will return \fBTrue\fP if the source has changed since +the last time it was saved or queried. The internal change flag is +reset whenever the string is queried via \fBXtGetValues\fP or the +buffer is saved via \fBXawAsciiSave\fP. diff --git a/spec/AsciiText b/spec/AsciiText new file mode 100644 index 0000000..815e0e1 --- /dev/null +++ b/spec/AsciiText @@ -0,0 +1,166 @@ +.\" $Xorg: AsciiText,v 1.3 2000/08/17 19:42:26 cpqbld Exp $ +.NH 2 +Ascii Text Widget +.LP +.XS + AsciiText Widget +.XE +.IN "AsciiText widget" "" "@DEF@" +.LP +.Ds 0 +.TA 2.0i +.ta 2.0i +Application Header file <X11/Xaw/AsciiText.h> +.IN "AsciiText.h" "" +ClassHeader file <X11/Xaw/AsciiTextP.h> +.IN "AsciiTextP.h" "" +Class asciiTextWidgetClass +.IN "asciiTextWidgetClass" "" +Class Name Text +.IN "AsciiText widget" "class name" +Superclass Text +Sink Name textSink +Source Name textSource +.De +.sp 1 +.LP +For the ease of internationalization, the AsciiText widget class name has not +been changed, although it is actually able to support non-ASCII locales. +The AsciiText widget is really a collection of smaller parts. It +includes the Text widget itself, a ``Source'' (which supports memory management), +and a ``Sink'' (which handles the display). There are currently two supported +sources, the AsciiSrc and MultiSrc, and two supported sinks, the AsciiSink and +.IN "AsciiSrc object" "" +.IN "AsciiSink object" "" +.IN "MultiSrc object" "" +.IN "MultiSink object" "" +MultiSink. Some of +the resources listed below are not actually resources of the +AsciiText, but belong to the associated source or sink. This is +is noted in the explanation of each resource where it applies. When +specifying these resources in a resource file it is necessary to use +\fI*AsciiText*resource_name\fP instead of +\fI*AsciiText.resource_name\fP, since they actually belong to the +children of the AsciiText widget, and not the AsciiText widget itself. +However, these resources may be set directly on the AsciiText widget at +widget creation time, or via \fBXtSetValues\fP. +.NH 3 +Resources +.LP +When creating an AsciiText widget instance, the following resources are +retrieved from the argument list or from the resource database: +.LP +.IN "AsciiText widget" "resources" +.TS H +expand; +lw(1i) lw(1i) lw(1.1i) lw(.5i) lw(1.9i). +_ +.sp 3p +.TB +Name Class Type Notes Default Value +.sp 3p +_ +.TH +.R +.sp 3p +accelerators Accelerators AcceleratorTable NULL +ancestorSensitive AncestorSensitive Boolean D True +autoFill AutoFill Boolean False +background Background Pixel XtDefaultBackground +backgroundPixmap Pixmap Pixmap XtUnspecifiedPixmap +borderColor BorderColor Pixel XtDefaultForeground +borderPixmap Pixmap Pixmap XtUnspecifiedPixmap +borderWidth BorderWidth Dimension 1 +bottomMargin Margin Position 2 +callback Callback XtCallbackList NULL +colormap Colormap Colormap Parent's Colormap +cursor Cursor Cursor XC_xterm +cursorName Cursor String NULL +dataCompression DataCompression Boolean True +depth Depth int C Parent's Depth +destroyCallback Callback XtCallbackList NULL +displayCaret Output Boolean True +displayNonprinting Output Boolean True +displayPosition TextPosition XawTextPosition 0 +echo Output Boolean True +editType EditType XawTextEditType XawtextRead +font Font XFontStruct* XtDefaultFont +fontSet FontSet XFontSet XtDefaultFontSet +foreground Foreground Pixel XtDefaultForeground +height Height Dimension A Font height + margins +insensitiveBorder Insensitive Pixmap GreyPixmap +insertPosition TextPosition int 0 +international International Boolean C False +leftMargin Margin Dimension 2 +length Length int A length of \fBstring\fP +mappedWhenManaged MappedWhenManaged Boolean True +pieceSize PieceSize XawTextPosition BUFSIZ +pointerColor Foreground Pixel XtDefaultForeground +pointerColorBackground Background Pixel XtDefaultBackground +resize Resize XawTextResizeMode XawtextResizeNever +rightMargin Margin Position 2 +screen Screen Screen R Parent's Screen +scrollHorizontal Scroll XawTextScrollMode XawtextScrollNever +scrollVertical Scroll XawTextScrollMode XawtextScrollNever +selectTypes SelectTypes XawTextSelectType* See above +sensitive Sensitive Boolean True +string String String NULL +textSink TextSink Widget An AsciiSink +textSource TextSource Widget An AsciiSrc +topMargin Margin Position 2 +translations Translations TranslationTable See above +type Type XawAsciiType XawAsciiString +useStringInPlace UseStringInPlace Boolean False +width Width Dimension 100 +wrap Wrap WrapMode XawtextWrapNever +x Position Position 0 +y Position Position 0 +.sp 3p +_ +.TE +.Ac +.As +.Af +.Bg +.Gp +.Bc +.Bp +.Bw +.Tm +.Oc AsciiText +.Cm +.Cu +.Cn +.Od AsciiText +.Dp +.Dc +.Tc +.Sd AsciiText +.Td +.Oe AsciiText +.Sh AsciiText +.Sf AsciiText +.Sn AsciiText +.Sg AsciiText +.Hw +.Ib +.Ti +.Ol AsciiText +.Mm +.Pf +.Pb +.Op AsciiText +.Tz +.Sc +.Ts +.St +.Se +.Os AsciiText +.To +.Tr +.Ot AsciiText +.Ou AsciiText +.Tw +.Xy + + diff --git a/spec/Box b/spec/Box new file mode 100644 index 0000000..22bfe39 --- /dev/null +++ b/spec/Box @@ -0,0 +1,139 @@ +.\" $Xorg: Box,v 1.3 2000/08/17 19:42:26 cpqbld Exp $ +.NH 2 +Box Widget +.LP +.XS + Box Widget +.XE +.IN "Box widget" "" "@DEF@" +.Ds 0 +.TA 2.0i +.ta 2.0i +.sp +Application Header file <X11/Xaw/Box.h> +.IN "Box.h" "" +Class Header file <X11/Xaw/BoxP.h> +.IN "BoxP.h" "" +Class boxWidgetClass +.IN "boxWidgetClass" "" +Class Name Box +.IN "Box widget" "class name" +Superclass Composite +.sp +.De +.LP +The Box widget provides geometry management of arbitrary widgets in a +box of a specified dimension. The children are rearranged when +resizing events occur either on the Box or its children, or when +children are managed or unmanaged. The Box widget always attempts to +pack its children as tightly as possible within the geometry allowed by +its parent. +.LP +Box widgets are commonly used to manage a related set of buttons and +are often called ButtonBox widgets, but the children are not +limited to buttons. The Box's children are arranged on a background that +has its own specified dimensions and color. +.NH 3 +Resources +.LP +When creating a Box widget instance, the following resources are +retrieved from the argument list or from the resource database: +.LP +.IN "Box widget" "resources" +.TS H +expand; +lw(1i) lw(1i) lw(1i) lw(.5i) lw(2i). +_ +.sp 3p +.TB +Name Class Type Notes Default Value +.sp 3p +_ +.TH +.R +.sp 3p +accelerators Accelerators AcceleratorTable NULL +ancestorSensitive AncestorSensitive Boolean D True +background Background Pixel XtDefaultBackground +backgroundPixmap Pixmap Pixmap XtUnspecifiedPixmap +borderColor BorderColor Pixel XtDefaultForeground +borderPixmap Pixmap Pixmap XtUnspecifiedPixmap +borderWidth BorderWidth Dimension 1 +children ReadOnly WidgetList R NULL +colormap Colormap Colormap Parent's Colormap +depth Depth int C Parent's Depth +destroyCallback Callback XtCallbackList NULL +height Height Dimension A see \fBLayout Semantics\fP +hSpace HSpace Dimension 4 +mappedWhenManaged MappedWhenManaged Boolean True +numChildren ReadOnly Cardinal R 0 +orientation Orientation Orientation XtorientVertical +screen Screen Screen R Parent's Screen +sensitive Sensitive Boolean True +vSpace VSpace Dimension 4 +translations Translations TranslationTable NULL +width Width Dimension A see \fBLayout Semantics\fP +x Position Position 0 +y Position Position 0 +.sp 3p +_ +.TE +.Ac +.As +.Bg +.Gp +.Bc +.Bp +.Bw +.Ch +.Cm +.Dp +.Dc +.Hw +.IP \fBhSpace\fP 1.5i +.br +.ns +.IP \fBvSpace\fP 1.5i +The amount of space, in pixels, to leave between the children. This +resource specifies the amount of space left between the outermost +children and the edge of the box. +.Mm +.Nc +.IP \fBorientation\fP 1.5i +Specifies whether the preferred shape of the box (i.e. the result +returned by the query_geometry class method) is tall and narrow +\fBXtorientVertical\fP or short and wide \fPXtorientHorizontal\fP. +.IN "XtorientVertical" "" +.IN "XtorientHorizontal" "" +.IN "conversions" "Orientation" +When the Box is a child of a parent which enforces width constraints, it +is usually better to specify \fBXtorientVertical\fP (the default). +When the parent enforces height constraints, it is usually better to +specify \fBXtorientHorizontal\fP. +.Rs "horizontal \fPand\fB vertical" +.Sc +.Se +.Tr +.Xy +.NH 3 +Layout Semantics +.IN "Box widget" "layout semantics" +.LP +Each time a child is managed or unmanaged, the Box widget will attempt +to reposition the remaining children to compact the box. Children are +positioned in order left to right, top to bottom. The packing +algorithm used depends on the \fBorientation\fP of the Box. +.IP \fBXtorientVertical\fP 1.5i +.IN "XtorientVertical" "" @DEF@ +When the next child does not fit on the current row, a new row is +started. If a child is wider than the width of the box, the box will +request a larger width from its parent and will begin the layout +process from the beginning if a new width is granted. +.IP \fBXtorientHorizontal\fP 1.5i +.IN "XtorientHorizontal" "" @DEF@ +When the next child does not fit on the current row, the Box widens if +possible (so as to keep children on a single row); otherwise a new row is +started. +.LP +After positioning all children, the Box widget attempts to shrink its +own size to the minimum dimensions required for the layout. diff --git a/spec/CH1 b/spec/CH1 new file mode 100644 index 0000000..b392a70 --- /dev/null +++ b/spec/CH1 @@ -0,0 +1,411 @@ +.\" $Xorg: CH1,v 1.3 2000/08/17 19:42:26 cpqbld Exp $ +.ps 11 +.nr PS 11 +.ds LH \fBAthena Widget Set\fP +.ds CH +.ds RH \fB\*(xV\fP +.bp 1 +.af PN 1 +\& +.sp 1 +.ce 3 +\s+1\fBChapter 1\fP\s-1 + +\s+1\fBAthena Widgets and The Intrinsics\fP\s-1 +.sp 2 +.nr H1 1 +.if \n(GS .nr nh*hl 1 +.nr H2 0 +.nr H3 0 +.nr H4 0 +.nr H5 0 +.LP +.XS +Chapter 1 \- Athena Widgets and The \*(xI +.XE +The X Toolkit is made up of two distinct pieces, the Xt \*(xI and a +widget set. The Athena widget set is a sample implementation of a +widget set built upon the \*(xI. In the \*(tk, a widget is the +combination of an X window or subwindow and its associated input and +output semantics. +.LP +Because the \*(xI provide the same basic functionality to all widget +sets it may be possible to use widgets from the Athena widget set with +other widget sets based upon the \*(xI. Since widget sets may also +implement private protocols, all functionality may not be available when +mixing and matching widget sets. For information about the \*(xI, see +the \fI\*(xT\fP. +.LP +The Athena widget set is a library package layered on top of the \*(xI +and Xlib that provides a set of user interface tools sufficient to build +a wide variety of applications. This layer extends the basic +abstractions provided by X and provides the next layer of functionality +primarily by supplying a cohesive set of sample widgets. Although the +\*(xI are a Consortium standard, there is no standard widget set. +.LP +To the extent possible, the \*(xI are "policy-free". The application +environment and widget set, not the \*(xI, define, implement, and +enforce: +.IP \(bu 5 +Policy +.IP \(bu 5 +Consistency +.IP \(bu 5 +Style +.LP +Each individual widget implementation defines its own policy. The \*(tk +design allows for, but does not necessarily encourage, the free mixing +of radically differing widget implementations. +.NH 2 +Introduction to the \*(tk +.LP +.XS + Introduction to the \*(tk +.XE +.IN "introduction" "" "@DEF@" +The \*(tk provides tools that simplify the design of +application user interfaces in the X Window System programming environment. +It assists application programmers by providing a set of common +underlying user-interface functions. It also lets widget programmers +modify existing widgets, by subclassing, or add new widgets. By using +the \*(tk in their applications, programmers can present a similar +user interface across applications to all workstation users. +.LP +The \*(tk consists of: +.IP \(bu 5 +A set of \*(xI functions for building widgets +.IP \(bu 5 +An architectural model for constructing widgets +.IP \(bu 5 +A widget set for application programming +.LP +While the majority of the \*(xI functions are intended +for the widget programmer, +a subset of the \*(xI functions are to be used by application programmers +(see \fI\*(xT\fP). +The architectural model lets the widget programmer design new widgets +by using the \*(xI and by combining other widgets. +The application interface layers built on top of the \*(tk include a +coordinated set of widgets and composition policies. +Some of these widgets and policies are specific to a single +application domain, and others are common to a variety of +applications. +.LP +The remainder of this chapter discusses the \*(tk and Athena widget set: +.IP \(bu 5 +Terminology +.IP \(bu 5 +Model +.IP \(bu 5 +Conventions used in this manual +.IP \(bu 5 +Format of the Widget Reference Chapters +.NH 2 +Terminology +.LP +.XS + Terminology +.XE +.LP +In addition to the terms already defined for X programming (see \fI\*(xL\fP), +the following terms are specific to the \*(xI and Athena widget set +and used throughout this document. +.LP +\fBApplication programmer\fP +.IN "application programmer" "" "@DEF@" +.IP +A programmer who uses the \*(tk to produce an application user interface. +.LP +\fBChild\fP +.IN "child" "" "@DEF" +.IP +A widget that is contained within another "parent" widget. +.LP +\fBClass\fP +.IN "class" "" "@DEF@" +.IP +The general group to which a specific object belongs. +.LP +\fBClient\fP +.IN "client" "" "@DEF@" +.IP +A function that uses a widget in an application or for composing +other widgets. +.LP +\fBFullName\fP +.IN "FullName" "" "@DEF" +.IP +The name of a widget instance appended to the full name of its parent. +.LP +\fBInstance\fP +.IN "instance" "" "@DEF@" +.IP +A specific widget object as opposed to a general widget class. +.LP +\fBMethod\fP +.IN "method" "" "@DEF@" +.IP +A function or procedure implemented by a widget class. +.LP +\fBName\fP +.IN "name" "widget" "@DEF@" +.IP +The name that is specific to an instance of a widget for a given client. +This name is specified at creation time and cannot be modified. +.LP +\fBObject\fP +.IN "object" "" "@DEF@" +.IP +A data abstraction consisting of private data and private and public +functions that operate on the private data. +Users of the abstraction can interact with the object only through calls +to the object's public functions. +In the \*(tk, +some of the object's public functions are called directly by the application, +while others are called indirectly when the application calls the common +\*(xI functions. +In general, if a function is common to all widgets, +an application uses a single \*(xI function to invoke the function for all +types of widgets. +If a function is unique to a single widget type, +the widget exports the function. +.LP +\fBParent\fP +.IN "parent" "" "@DEF@" +.IP +A widget that contains at least one other ("child") widget. +A parent widget is also known as a composite widget. +.LP +\fBResource\fP +.IN "resource" "" "@DEF@" +.IP +A named piece of data in a widget that can be set by a client, +by an application, or by user defaults. +.LP -- To UNSUBSCRIBE, email to debian-x-requ...@lists.debian.org with a subject of "unsubscribe". Trouble? Contact listmas...@lists.debian.org