diff options
Diffstat (limited to 'xc/doc/specs/Xaw')
48 files changed, 0 insertions, 16626 deletions
diff --git a/xc/doc/specs/Xaw/AsciiSink b/xc/doc/specs/Xaw/AsciiSink deleted file mode 100644 index 0da523733..000000000 --- a/xc/doc/specs/Xaw/AsciiSink +++ /dev/null @@ -1,77 +0,0 @@ -.\" $XConsortium: AsciiSink,v 1.10 94/05/02 08:33:09 gildea 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/xc/doc/specs/Xaw/AsciiSource b/xc/doc/specs/Xaw/AsciiSource deleted file mode 100644 index bc5bd47db..000000000 --- a/xc/doc/specs/Xaw/AsciiSource +++ /dev/null @@ -1,208 +0,0 @@ -.\" $XConsortium: AsciiSource,v 1.13 94/05/02 08:30:49 gildea 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, \fBXawAsciiSrcFreeString\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 \fBXawAsciiSrcFreeString\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/xc/doc/specs/Xaw/AsciiText b/xc/doc/specs/Xaw/AsciiText deleted file mode 100644 index a3a927548..000000000 --- a/xc/doc/specs/Xaw/AsciiText +++ /dev/null @@ -1,166 +0,0 @@ -.\" $XConsortium: AsciiText,v 1.22 94/05/01 19:21:15 gildea 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 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/xc/doc/specs/Xaw/Box b/xc/doc/specs/Xaw/Box deleted file mode 100644 index 845ebbf95..000000000 --- a/xc/doc/specs/Xaw/Box +++ /dev/null @@ -1,139 +0,0 @@ -.\" $XConsortium: Box,v 1.20 94/05/01 20:44:56 gildea 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/xc/doc/specs/Xaw/CH1 b/xc/doc/specs/Xaw/CH1 deleted file mode 100644 index eb323ce39..000000000 --- a/xc/doc/specs/Xaw/CH1 +++ /dev/null @@ -1,411 +0,0 @@ -.\" $TOG: CH1 /main/17 1997/11/04 18:18:31 kaleb $ -.ps 11 -.nr PS 11 -.ds LH \fBAthena Widget Set\fP -.ds CH -.ds RH \fBX11, Release 6.4\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 -\fBSuperclass\fP -.IN "superclass" "" "@DEF@" -.IP -A larger class of which a specific class is a member. -All members of a class are also members of the superclass. -.LP -\fBUser\fP -.IN "user" "" "@DEF@" -.IP -A person interacting with a workstation. -.LP -\fBWidget\fP -.IN "widget" "" "@DEF@" -.IP -An object providing a user-interface abstraction (for example, a Scrollbar -widget). -.LP -\fBWidget class\fP -.IN "widget class" "" "@DEF@" -.IP -The general group to which a specific widget belongs, -otherwise known as the type of the widget. -.LP -\fBWidget programmer\fP -.IN "widget programmer" "" "@DEF@" -.IP -A programmer who adds new widgets to the \*(tk. -.NH 2 -Underlying Model -.LP -.XS - Underlying Model -.XE -.IN "underlying model" "" "@DEF@" -The underlying architectural model is based on the following premises: -.KS -.IP "Widgets are X windows" -.IP -Every user-interface widget is associated with an X window. -The X window ID for a widget is readily available from the widget. -Standard Xlib calls can be used by widgets for many of their input and -output operations. -.KE -.KS -.IP "Information hiding" -.IP -The data for every widget is private to the widget and its subclasses. -That is, the data is neither directly accessible -nor visible outside of the module implementing the widget. -All program interaction with the widget is performed by a set of operations -(methods) that are defined for the widget. -.KE -.KS -.IP "Widget semantics and widget layout geometry" -.IP -Widget semantics are clearly separated from widget layout geometry. -Widgets are concerned with implementing specific user-interface -semantics. They have little control over issues such as their size or -placement relative to other widget peers. Mechanisms are provided for -associating geometric managers with widgets and for widgets to make -suggestions about their own geometry. -.KE -.NH 2 -Conventions Used in this Manual -.IP \(bu 5 -.IN "conventions" "used in manual" "@DEF@" -All resources available to the widgets are listed with each widget. Many -of these are available to more than one widget class due to the object -oriented nature of the \*(xI. The new resources for each widget are -listed in bold text, and the inherited resources are listed in plain text. -.IP \(bu 5 -Global symbols are printed in \fBbold\fP and can be function names, -symbols defined in include files, or structure names. Arguments 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. Where -applicable, the last paragraph of the explanation lists the return values -of the function. -.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. The explanations for all arguments that you can pass -and are returned start with the words \fIspecifies and returns\fP. -.IP \(bu 5 -Any pointer to a structure that is used to return a value is -designated as such by the \fI_return\fP suffix as part of its name. -All other pointers passed to these functions are used for reading -only. A few arguments use pointers to structures that are used for -both input and output and are indicated by using the \fI_in_out\fP -suffix. -.IN "_return" "" "@DEF@" -.IN "_in_out" "" "@DEF@" -.NH 2 -Format of the Widget Reference Chapters -.LP -.IN "conventions" "chapter format" "@DEF@" -.IN "chapter format" "" "@DEF@" -The majority of this document is a reference guide for the Athena -widget set. Chapters three through six give the programmer all -information necessary to use the widgets. The layout of the chapters -follows a specific pattern to allow the programmer to easily find the -desired information. -.LP -The first few pages of every chapter give an overview of the widgets -in that section. Widgets are grouped into chapters by functionality. -.IP "Chapter 3" .75i -Simple Widgets -.IP "Chapter 4" .75i -Menus -.IP "Chapter 5" .75i -Text Widgets -.IP "Chapter 6" .75i -Composite and Constraint Widget -.LP -Following the introduction will be a description of each widget in that -chapter. When no functional grouping is obvious the widgets are listed -in alphabetical order, such as in chapters three and six. -.LP -The first section of each widget's description is a table that -contains general information about this widget class. Here is the -table for the Box widget, and an explanation of all the entries. -.Ds 0 -.TA 2.0i -.ta 2.0i -.sp -Application Header file <X11/Xaw/Box.h> -Class Header file <X11/Xaw/BoxP.h> -Class boxWidgetClass -Class Name Box -Superclass Composite -.sp -.De -.IP "\fBApplication Header File\fP" 2.0i -.IN "application header file" "" "@DEF@" -This file must be included when an application uses this widget. -It usually contains the class definition, and some resource macros. -This is often called the ``public'' header file. -.IN "class header file" "" "@DEF@" -.IP "\fBClass Header File\fP" 2.0i -This file will only be used by widget programmers. It will need to be -included by any widget that subclasses this widget. This is often -called the ``private'' header file. -.IN "class" "" "@DEF@" -.IP \fBClass\fP 2.0i -This is the widget class of this widget. This global symbol is passed to -\fBXtCreateWidget\fP so that the \*(xI will know which type of widget -to create. -.IN "class name" "" "@DEF@" -.IP "\fBClass Name\fP" 2.0i -This is the resource name of this class. This name can be used in -a resource file to match any widget of this class. -.IN "superclass" "" -.IP \fBSuperclass\fP 2.0i -This is the superclass that this widget class is descended from. If -you understand how the superclass works it will allow you to more quickly -understand what this widget does, since much of its functionality may be -inherited from its superclass. -.sp -.LP -After this table follows a general description of the default behavior of -this widget, as seen by the user. In many cases this functionality -may be overridden by the application programmer, or by the user. -.LP -The next section is a table showing the -name, class, type and default value of each resource that is available -to this widget. There is also a column containing notes describing -special restrictions placed upon individual resources. -.IN "notes" "" "@DEF@" -.IN "A, note" "" "@DEF@" -.IN "D, note" "" "@DEF@" -.IN "C, note" "" "@DEF@" -.IN "R, note" "" "@DEF@" -.IP A .5i -This resource may be automatically adjusted when another -resource is changed. -.IP C .5i -This resource is only settable at widget creation time, and may not -be modified with \fBXtSetValues\fP. -.IP D .5i -Do not modify this resource. While setting this resource will -work, it can cause unexpected behavior. When this symbol appears -there is another, preferred, interface provided by the \*(tk. -.IP R .5i -This resource is READ-ONLY, and may not be modified. -.LP -After the resource table is a detailed description of every resource -available to that widget. Many of these are redundant, but printing -them with each widget saves page flipping. The names of the resources -that are inherited are printed in plain text, while the names of the -resources that are new to this class are printed in \fBbold\fP. -If you have already read the description of the superclass you need -only pay attention to the resources printed in bold. -.LP -For each composite widget there is a section on layout semantics that -follows the resource description. This section will describe the -effect of constraint resources on the layout of the children, as well -as a general description of where it prefers to place its children. -.LP -Descriptions of default translations and action routines come next, for -widgets to which they apply. The last item in each widget's -documentation is the description of all convenience routines provided by -the widget. -.NH 2 -Input Focus -.XS - Input Focus -.XE -.IN "input focus" "" "@DEF@" -.IN "input" "" "@DEF@" -.IN "XtNinput" "" "@DEF@" -.LP -The \*(xI define a resource on all Shell widgets that interact with -the window manager called \fBinput\fP. This resource requests the -assistance of window manager in acquiring the input focus. The -resource defaults to \fBFalse\fP in the \*(xI, but is redefined to -default to \fBTrue\fP when an application is using the Athena widget -set. An application programmer may override this default and set the -resource back to \fBFalse\fP if the application does not need the window -manager to give it the input focus. See the \fI\*(xT\fP for details -on the \fIinput\fP resource. diff --git a/xc/doc/specs/Xaw/CH2 b/xc/doc/specs/Xaw/CH2 deleted file mode 100644 index 497aa7f5a..000000000 --- a/xc/doc/specs/Xaw/CH2 +++ /dev/null @@ -1,1103 +0,0 @@ -.\" $XConsortium: CH2,v 1.21 94/05/01 20:33:23 gildea Exp $ -.bp -\& -.sp 1 -.ce 3 -\s+1\fBChapter 2\fP\s-1 - -\s+1\fBUsing Widgets\fP\s-1 -.sp 2 -.nr H1 2 -.nr H2 0 -.nr H3 0 -.nr H4 0 -.nr H5 0 -.LP -.XS -Chapter 2 \- Using Widgets -.XE -.IN "using widgets" "" "@DEF@" -Widgets serve as the primary tools for building a user interface or -application environment. The Athena widget set consists of primitive -widgets that contain no children (for example, a command button) and -composite widgets which may contain one or more widget children (for -example, a Box widget). -.LP -The remaining chapters explain the widgets that are provided -by the Athena widget set. -These user-interface components serve as an interface for -application programmers who do not want to implement their own widgets. -In addition, they serve as a starting point -for those widget programmers who, using the \*(xI mechanisms, -want to implement alternative application programming interfaces. -.LP -This chapter is a brief introduction to widget programming. The -examples provided use the Athena widgets, though most of the concepts -will apply to all widget sets. Although there are several programming -interfaces to the \*(tk, only one is described here. A full -description of the programming interface is provided in the document -\fI\*(xT\fP. -.NH 2 -Setting the Locale -.LP -.XS - Setting the Locale -.XE -If it is desirable that the application take advantage of -internationalization (i18n), you must establish locale with -.PN XtSetLanguageProc -before \fBXtDisplayInitialize\fP or \fBXtAppInitialize\fP -is called. For full details, please refer to the document -\fI\*(xT\fP, section 2.2. However, the following simplest-case -call is sufficient in many or most applications. -.LP -.IN "internationalization" "" "" -.IN "XtSetLanguageProc" "" "@DEF@" -.IN "locale" "" "" -.Ds -.TA .5i 2i -.ta .5i 2i - XtSetLanguageProc(NULL, NULL, NULL); -.De -.LP -Most notably, this will affect the Standard C locale, determine which -resource files will be loaded, and what fonts will be required of FontSet -specifications. In many cases, the addition of this line is the only source change -required to internationalize Xaw programs, and will not disturb the function -of programs in the default "C" locale. -.NH 2 -Initializing the Toolkit -.LP -.XS - Initializing the Toolkit -.XE -You must call a toolkit initialization function before invoking any -other toolkit routines (besides locale setting, above). -.PN XtAppInitialize -opens the X server connection, parses the command line, -and creates an initial widget that will serve as the root of -a tree of widgets created by this application. -.IN "initialization" "" "@DEF@" -.IN "toolkit initialization" "" "@DEF@" -.IN "XtAppInitialize" "" "@DEF@" -.IN "fallback resources" "" "@DEF@" -.FD 0 -Widget XtAppInitialize(\fIapp_context_return\fP, \fIapplication_class\fP, \ -\fIoptions\fP, \fInum_options\fP, -.ta 2i - \fIargc_in_out\fP, \fIargv_in_out\fP, \fIfallback_resources\fP, \ -\fIargs\fP, \fInum_args\fP) -.br - XtAppContext *\fIapp_context_return\fP; -.br - String \fIapplication_class\fP; -.br - XrmOptionDescRec \fIoptions\fP[]; -.br - Cardinal \fInum_options\fP; -.br - int *\fIargc_in_out\fP; -.br - String *\fIargv_in_out\fP[]; -.br - String *\fIfallback_resources\fP; -.br - ArgList \fIargs\fP; -.br - Cardinal \fInum_args\fP; -.FN -.IP \fIapp_con_return\fP 1.5i -Returns the application context of this application, if non-NULL. -.IP \fIapplication_class\fP 1.5i -Specifies the class name of this application, -which is usually the generic name for all instances of this application. -A useful convention is to form the class name by capitalizing the -first letter of the application name. For example, the application named -``xman'' has a class name of ``Xman''. -.IP \fIoptions\fP 1.5i -Specifies how to parse the command line for any application-specific -resources. -The options argument is passed as a parameter to -.PN XrmParseCommand . -For further information, -see \fI\*(xL\fP. -.IP \fInum_options\fP 1.5i -Specifies the number of entries in the options list. -.IP \fIargc_in_out\fP 1.5i -Specifies a pointer to the number of command line parameters. -.IP \fIargv_in_out\fP 1.5i -Specifies the command line parameters. -.IP \fIfallback_resources\fP 1.5i -Specifies resource values to be used if the site-wide application class -defaults file cannot be opened, or NULL. -.IP \fIargs\fP 1.5i -Specifies the argument list to use when creating the Application shell. -.IP \fInum_args\fP 1.5i -Specifies the number of arguments in \fIargs\fP. -.LP -This function will remove the command line arguments that the toolkit -reads from \fIargc_in_out\fP, and \fIargv_in_out\fP. It will then -attempt to open the display. If the display cannot be opened, an error -message is issued and XtAppInitialize terminates the application. Once -the display is opened, all resources are read from the locations -specified by the \*(xI. This function returns an ApplicationShell -widget to be used as the root of the application's widget tree. -.NH 2 -Creating a Widget -.LP -.XS - Creating a Widget -.XE -.IN "widget creation" "" "@DEF@" -.IN "creating widgets" "" "@DEF@" -.IN "XtRealizeWidget" "" "" -Creating a widget is a three-step process. First, the widget instance -is allocated, and various instance-specific attributes are set by -using \fBXtCreateWidget\fP. Second, the widget's parent is informed -of the new child by using \fBXtManageChild\fP. Finally, X windows are -created for the parent and all its children by using \fBXtRealizeWidget\fP -and specifying the top-most widget. The first two steps can be -combined by using \fBXtCreateManagedWidget\fP. In addition, -\fBXtRealizeWidget\fP is automatically called when the child becomes -managed if the parent is already realized. -.LP -To allocate, initialize, and manage a widget, use -.PN XtCreateManagedWidget . -.IN "XtCreateManagedWidget" "" "@DEF@" -.FD 0 -Widget XtCreateManagedWidget(\fIname\fP, \fIwidget_class\fP, \fIparent\fP, \ -\fIargs\fP, \fInum_args\fP) -.br - String \fIname\fP; -.br - WidgetClass \fIwidget_class\fP; -.br - Widget \fIparent\fP; -.br - ArgList \fIargs\fP; -.br - Cardinal \fInum_args\fP; -.FN -.IP \fIname\fP 1i -Specifies the instance name for the created widget that is used for retrieving -widget resources. -.IP \fIwidget_class\fP 1i -Specifies the widget class pointer for the created widget. -.IP \fIparent\fP 1i -Specifies the parent widget ID. -.IP \fIargs\fP 1i -Specifies the argument list. The argument list is a variable-length -list composed of name and value pairs that contain information -pertaining to the specific widget instance being created. For further -information, see Section 2.7.2. -.IP \fInum_args\fP 1i -Specifies the number of arguments in the argument list. -If the num_args is zero, the argument list is never referenced. -.LP -When a widget instance is successfully created, the widget identifier -is returned to the application. If an error is encountered, the -.PN XtError -routine is invoked to inform the user of the error. -.IN "XtError" "" "" -.LP -For further information, see \fI\*(xT\fP. -.NH 2 -Common Resources -.XS - Common Resources -.XE -.IN "resource" "" -.LP -Although a widget can have unique arguments that it understands, all -widgets have common arguments that provide some regularity of operation. -The common arguments allow arbitrary widgets to be managed by -higher-level components without regard for the individual widget type. -Widgets will ignore any argument that they do not understand. -.LP -The following resources are retrieved from the argument list -or from the resource database by all of the Athena widgets: -.TS H -lw(1.5i) lw(1i) lw(1i) lw(2i). -_ -.sp 3p -.TB -Name Class Type Default Value -.sp 3p -_ -.TH -.R -.sp 3p -accelerators Accelerators AcceleratorTable NULL -ancestorSensitive AncestorSensitive Boolean True -background Background Pixel XtDefaultBackground -backgroundPixmap Pixmap Pixmap XtUnspecifiedPixmap -borderColor BorderColor Pixel XtDefaultForeground -borderPixmap Pixmap Pixmap XtUnspecifiedPixmap -borderWidth BorderWidth Dimension 1 -colormap Colormap Colormap Parent's Colormap -depth Depth int Parent's Depth -destroyCallback Callback XtCallbackList NULL -height Height Dimension \fIwidget dependent\fP -mappedWhenManaged MappedWhenManaged Boolean True -screen Screen Screen Parent's Screen -sensitive Sensitive Boolean True -translations Translations TranslationTable \fIwidget dependent\fP -width Width Dimension \fIwidget dependent\fP -x Position Position 0 -y Position Position 0 -.sp 3p -_ -.TE -.IN "XtDefaultForeground" "" "" -.IN "XtDefaultBackground" "" "" -.LP -The following additional resources are retrieved from the argument list -or from the resource database by many of the Athena widgets: -.TS H -lw(1.5i) lw(1i) lw(1i) lw(2i). -_ -.sp 3p -.TB -Name Class Type Default Value -.sp 3p -_ -.TH -.R -.sp 3p -callback Callback XtCallbackList NULL -cursor Cursor Cursor \fIwidget dependent\fP -foreground Foreground Pixel XtDefaultForeground -insensitiveBorder Insensitive Pixmap GreyPixmap -.sp 3p -_ -.TE -.IN "XtDefaultForeground" "" "" -.NH 2 -Resource Conversions -.XS - Resource Conversions -.XE -.IN "conversions" "" "@DEF@" -.IN "string conversions" "" "@DEF@" -.IN "type conversions" "" "@DEF@" -.LP -Most resources in the Athena widget set have a converter registered that -will translate the string in a resource file to the correct internal -representation. While some are obvious (string to integer, for example), -others need specific mention of the allowable values. Three general -converters are described here: -.IP \(bu 5 -Cursor -.IP \(bu 5 -Pixel -.IP \(bu 5 -Bitmap -.LP -Many widgets have defined special converters that apply only to that -widget. When these occur, the documentation section for that widget -will describe the converter. -.NH 3 -Cursor Conversion -.IN "conversions" "ColorCursor" "@DEF@" -.IN "conversions" "Cursor" "@DEF@" -.IN "cursor" "" "" -.LP -The value for the \fBcursorName\fP resource is specified in the resource -database as a string, and is of the following forms: -.IP \(bu 5 -A standard X cursor name from \fB< X11/cursorfont.h >\fP. -The names in \fBcursorfont.h\fP each describe a specific cursor. The -resource names for these cursors are exactly like the names in this file -except the \fBXC_\fP is not used. The cursor definition \fBXC_gumby\fP -has a resource name of \fBgumby\fP. -.IP \(bu 5 -Glyphs, as in \fIFONT font-name glyph-index [[ font-name ] glyph-index ]\fP. -The first font and glyph specify the cursor source pixmap. -The second font and glyph specify the cursor mask pixmap. -The mask font defaults to the source font, -and the mask glyph index defaults to the source glyph index. -.IP \(bu 5 -A relative or absolute file name. -If a relative or absolute file name is specified, that file is used to -create the source pixmap. Then the string "Mask" is appended to -locate the cursor mask pixmap. If the "Mask" file does not exist, the -suffix "msk" is tried. If "msk" fails, no cursor mask will be used. -If the filename does not start with '/' or './' the the bitmap -file path is used (see section 2.4.3). -.NH 3 -Pixel Conversion -.LP -.IN "conversions" "Pixel" "@DEF@" -.IN "pixel" "" "" -.IN "rgb.txt" "" "" -.IN "XtDefaultForeground" "" "" -.IN "XtDefaultBackground" "" "" -The string-to-pixel converter takes any name that is acceptable to -XParseColor (see \fI\*(xL\fP). In addition this routine understands -the special toolkit symbols `XtDefaultForeground' and -`XtDefaultBackground', described in \fI\*(xT\fP. In short the acceptable -pixel names are: -.IP \(bu 5 -Any color name for the rgb.txt file (typically in the directory -/usr/lib/X11 on POSIX systems). -.IP \(bu 5 -A numeric specification of the form #<red><green><blue> where these -numeric values are hexadecimal digits (both upper and lower case). -.IP \(bu 5 -The special strings `XtDefaultForeground' and `XtDefaultBackground' -.NH 3 -Bitmap Conversion -.IN "bitmap conversions" "" "@DEF@" -.IN "conversions" "Bitmap" "@DEF@" -.IN "bitmapFilePath" "" "@DEF@" -.IN "BitmapFilePath" "" "@DEF@" -.IN "/usr/include/X11/bitmaps" "" "" -.LP -The string-to-bitmap converter attempts to locate a file containing -bitmap data whose name is specified by the input string. If the file -name is relative (i.e. does not begin with / or ./), the directories to -be searched are specified in the \fBbitmapFilePath\fP resource--class -\fBBitmapFilePath\fP. This resource specifies a colon (:) separated -list of directories that will be searched for the named bitmap or -cursor glyph (see section 2.4.1). The \fBbitmapFilePath\fP resource is -global to the application, and may \fBnot\fP be specified differently -for each widget that wishes to convert a cursor to bitmap. In addition -to the directories specified in the \fBbitmapFilePath\fP resource a -default directory is searched. When using POSIX the default -directory is -.PN /usr/include/X11/bitmaps . -.NH 2 -Realizing a Widget -.LP -.XS - Realizing a Widget -.XE -.IN "realizing widgets" "" "@DEF@" -The -.PN XtRealizeWidget -function performs two tasks: -.IP \(bu 5 -Calculates the geometry constraints of all managed descendants -of this widget. The actual calculation is put off until realize time -for performance reasons. -.IP \(bu 5 -Creates an X window for the widget and, if it is a composite widget, -realizes each of its managed children. -.IN "XtRealizeWidget" "" "@DEF@" -.FD 0 -void XtRealizeWidget(\fIw\fP) -.br - Widget \fIw\fP; -.FN -.IP \fIw\fP 1i -Specifies the widget. -.LP -For further information about this function, -see the \fI\*(xT\fP. -.NH 2 -Processing Events -.LP -.XS - Processing Events -.XE -.IN "events" "" "" -.IN "XtAppInitialize" "" "" -Now that the application has created, managed and realized its -widgets, it is ready to process the events that will be delivered by the -X Server to this client. A function call that will process the -events is \fBXtAppMainLoop\fP. -.IN "XtAppMainLoop" "" "@DEF@" -.FD 0 -void XtAppMainLoop(\fIapp_context\fP) -.br - XtAppContext \fIapp_context\fP; -.FN -.IP \fIapp_context\fP 1i -Specifies the application context of this application. The value is -normally returned by \fBXtAppInitialize\fP. -.LP -This function never returns: it is an infinite loop that processes the -X events. User input can be handled through callback procedures and -application defined action routines. More details are provided in -\fI\*(xT\fP. -.NH 2 -Standard Widget Manipulation Functions -.XS - Standard Widget Manipulation Functions -.XE -.LP -After a widget has been created, a client can interact with that -widget by calling one of the standard widget manipulation routines -provided by the \*(xI, or a widget class-specific manipulation routine. -.LP -The \*(xI provide generic routines to give the application programmer -access to a set of standard widget functions. The common widget -routines let an application or composite widget perform the following -operations on widgets without requiring explicit knowledge of the widget -type. -.IP \(bu 5 -Control the mapping of widget windows -.IP \(bu 5 -Destroy a widget instance -.IP \(bu 5 -Obtain an argument value -.IP \(bu 5 -Set an argument value -.NH 3 -Mapping Widgets -.LP -By default, -widget windows are mapped (made viewable) automatically by -\fBXtRealizeWidget\fP. This behavior can be disabled by using -\fBXtSetMappedWhenManaged\fP, making the client responsible for calling -\fBXtMapWidget\fP to make the widget viewable. -.IN "XtSetMappedWhenManaged" "" "@DEF@" -.IN "XtMapWidget" "" "" -.IN "XtRealizeWidget" "" "" -.FD 0 -void XtSetMappedWhenManaged(\fIw\fP, \fImap_when_managed\fP) -.br - Widget \fIw\fP; -.br - Boolean \fImap_when_managed\fP; -.FN -.IP \fIw\fP 1i -Specifies the widget. -.IP \fImap_when_managed\fP 1i -Specifies the new value. -If map_when_managed is \fBTrue\fP, the widget is mapped automatically -when it is realized. If map_when_managed is \fBFalse\fP, the client -must call -.PN XtMapWidget -or make a second call to -.PN XtSetMappedWhenManaged -to cause the child window to be mapped. -.LP -.sp -The definition for -.PN XtMapWidget -is: -.IN "XtMapWidget" "" "@DEF@" -.FD 0 -void XtMapWidget(\fIw\fP) -.br - Widget \fIw\fP; -.FN -.IP \fIw\fP 1i -Specifies the widget. -.LP -When you are creating several children in sequence for a previously -realized common parent it is generally more efficient to construct a -list of children as they are created (using \fBXtCreateWidget\fP) and -then use \fBXtManageChildren\fP to request that their parent managed -them all at once. By managing a list of children at one time, the -parent can avoid wasteful duplication of geometry processing and the -associated ``screen flash''. -.IN "XtManageChildren" "" "@DEF@" -.IN "XtCreateWidget" "" "" -.FD 0 -void XtManageChildren(\fIchildren\fP, \fInum_children\fP) -.br - WidgetList \fIchildren\fP; -.br - Cardinal \fInum_children\fP; -.FN -.IP \fIchildren\fP 1i -Specifies a list of children to add. -.IP \fInum_children\fP 1i -Specifies the number of children to add. -.LP -If the parent is already visible on the screen, it is especially -important to batch updates so that the minimum amount of visible window -reconfiguration is performed. -.LP -For further information about these functions, -see the \fI\*(xT\fP. -.NH 3 -Destroying Widgets -.LP -To destroy a widget instance of any type, use -.PN XtDestroyWidget . -.IN "XtDestroyWidget" "" "@DEF@" -.FD 0 -void XtDestroyWidget(\fIw\fP) -.br - Widget \fIw\fP; -.FN -.IP \fIw\fP 1i -Specifies the widget. -.LP -.PN XtDestroyWidget -destroys the widget and recursively destroys any children that it may have, -including the windows created by its children. -After calling -.PN XtDestroyWidget , -no further references should be made to the widget or any children -that the destroyed widget may have had. -.NH 3 -Retrieving Widget Resource Values -.LP -To retrieve the current value of a resource attribute associated -with a widget instance, use -.PN XtGetValues . -.IN "XtGetValues" "" "@DEF@" -.FD 0 -void XtGetValues(\fIw\fP, \fIargs\fP, \fInum_args\fP) -.br - Widget \fIw\fP; -.br - ArgList \fIargs\fP; -.br - Cardinal \fInum_args\fP; -.FN -.IP \fIw\fP 1i -Specifies the widget. -.IP \fIargs\fP 1i -Specifies a variable-length argument list of name and \fBaddress\fP -pairs that contain the resource name and the address into which the -resource value is stored. -.IP \fInum_args\fP 1i -Specifies the number of arguments in the argument list. -.LP -The arguments and values passed in the argument list are dependent on -the widget. Note that the caller is responsible for providing space -into which the returned resource value is copied; the \fBArgList\fP -contains a pointer to this storage (e.g. x and y must be -allocated as Position). For further information, see the \fI\*(xT\fP. -.NH 3 -Modifying Widget Resource Values -.LP -To modify the current value of a resource attribute associated with a -widget instance, use -.PN XtSetValues . -.IN "XtSetValues" "" "@DEF@" -.FD 0 -void XtSetValues(\fIw\fP, \fIargs\fP, \fInum_args\fP) -.br - Widget \fIw\fP; -.br - ArgList \fIargs\fP; -.br - Cardinal \fInum_args\fP; -.FN -.IP \fIw\fP 1i -Specifies the widget. -.IP \fIargs\fP 1i -Specifies an array of name and \fBvalue\fP pairs that contain the -arguments to be modified and their new values. -.IP \fInum_args\fP 1i -Specifies the number of arguments in the argument list. -.LP -The arguments and values that are passed will depend on the widget -being modified. Some widgets may not allow certain resources to be -modified after the widget instance has been created or realized. -No notification is given if any part of a \fBXtSetValues\fP request is -ignored. -.LP -For further information about these functions, see the \fI\*(xT\fP. -.IN "XtGetValues" "" "" -.IN "XtSetValues" "" "" -.NT -The argument list entry for -.PN XtGetValues -specifies the address to which the caller wants the value copied. The -argument list entry for -.PN XtSetValues , -however, contains the new value itself, if the size of value is less than -sizeof(XtArgVal) (architecture dependent, but at least sizeof(long)); -otherwise, it is a pointer to the value. String resources are always -passed as pointers, regardless of the length of the string. -.NE -.NH 2 -Using the Client Callback Interface -.LP -.XS - Using the Client Callback Interface -.XE -.IN "callbacks" "" "" -Widgets can communicate changes in their state to their clients -by means of a callback facility. -The format for a client's callback handler is: -.IN "CallbackProc" "" "@DEF@" -.FD 0 -void \fICallbackProc\fP(\fIw\fP, \fIclient_data\fP, \fIcall_data\fP) -.br - Widget \fIw\fP; -.br - XtPointer \fIclient_data\fP; -.br - XtPointer \fIcall_data\fP; -.FN -.IP \fIw\fP 1i -Specifies widget for which the callback is registered. -.IP \fIclient_data\fP 1i -Specifies arbitrary client-supplied data that the widget should pass -back to the client when the widget executes the client's callback -procedure. This is a way for the client registering the callback to -also register client-specific data: a pointer to additional information -about the widget, a reason for invoking the callback, and so on. If no -additional information is necessary, NULL may be passed as this argument. -This field is also frequently known as the \fIclosure\fP. -.IP \fIcall_data\fP 1i -Specifies any callback-specific data the widget wants to pass to the client. -For example, when Scrollbar executes its \fBjumpProc\fP callback list, -it passes the current position of the thumb in \fIcall_data\fP. -.LP -Callbacks can be registered either by creating an argument containing -the callback list described below or by using the special convenience -routines \fBXtAddCallback\fP and \fBXtAddCallbacks\fP. When the widget -is created, a pointer to a list of callback procedure and data pairs can -be passed in the argument list to -.PN XtCreateWidget . -The list is of type -.PN XtCallbackList : -.IN "XtCallbackProc" -.IN "XtAddCallbacks" -.IN "XtAddCallback" -.IN "XtCallbackList" "" "@DEF@" -.IN "XtCallbackRec" "" "@DEF@" -.LP -.Ds 0 -.TA .5i 3i -.ta .5i 3i -typedef struct { - XtCallbackProc callback; - XtPointer closure; -} XtCallbackRec, *XtCallbackList; -.De -.LP -The callback list must be allocated and initialized before calling -.PN XtCreateWidget . -.IN "XtCreateWidget" -The end of the list is identified by an entry containing NULL in -callback and closure. Once the widget is created, the client can change -or de-allocate this list; the widget itself makes no further reference -to it. The closure field contains the client_data passed to the -callback when the callback list is executed. -.LP -The second method for registering callbacks is to use -.PN XtAddCallback -after the widget has been created. -.IN "XtAddCallback" "" "@DEF@" -.FD 0 -void XtAddCallback(\fIw\fP, \fIcallback_name, \fP\fIcallback\fP, \ -\fIclient_data\fP) -.br - Widget \fIw\fP; -.br - String \fIcallback_name\fP; -.br - XtCallbackProc \fIcallback\fP; -.br - XtPointer \fIclient_data\fP; -.FN -.IP \fIw\fP 1i -Specifies the widget to add the callback to. -.IP \fIcallback_name\fP 1i -Specifies the callback list within the widget to append to. -.IP \fIcallback\fP 1i -Specifies the callback procedure to add. -.IP \fIclient_data\fP 1i -Specifies the data to be passed to the callback when it is invoked. -.LP -.PN XtAddCallback -adds the specified callback to the list for the named widget. -.LP -All widgets provide a callback list named -.PN destroyCallback -.IN "destroyCallback" "" "@DEF@" -where clients can register procedures that are to be executed when the -widget is destroyed. The destroy callbacks are executed when the widget -or an ancestor is destroyed. The \fIcall_data\fP argument is unused for -destroy callbacks. -.NH 2 -Programming Considerations -.LP -.XS - Programming Considerations -.XE -This section provides some guidelines on how to set up an application -program that uses the \*(tk. -.NH 3 -Writing Applications -.LP -.IN "writing applications" -.IN "StringDefs.h" -.IN "Intrinsic.h" -When writing an application that uses the X Toolkit, -you should make sure that your application performs the following: -.IP 1. 5 -Include -.Pn < X11/Intrinsic.h > -in your application programs. -This header file automatically includes -.Pn < X11/Xlib.h >, -so all Xlib functions also are defined. -It may also be necessary to include \fB< X11/StringDefs.h >\fP when setting -up argument lists, as many of the XtN\fIsomething\fP definitions are -only defined in this file. -.IP 2. 5 -Include the widget-specific header files for each widget type -that you need to use. -For example, -.Pn < X11/Xaw/Label.h > -and -.Pn < X11/Xaw/Command.h >. -.IP 3. 5 -Call the -.PN XtAppInitialize -.IN "XtAppInitialize" -function before invoking any other toolkit or Xlib functions. -For further information, -see Section 2.1 and the \fI\*(xT\fP. -.IP 4. 5 -To pass attributes to the widget creation routines that will override -any site or user customizations, set up argument lists. In this -document, a list of valid argument names is provided in the discussion -of each widget. The names each have a global symbol defined that begins -with \fBXtN\fP to help catch spelling errors. For example, -\fBXtNlabel\fP is defined for the \fBlabel\fP resource of many widgets. -.IN "XtN" "" "@DEF@" -.IP -For further information, see Section 2.9.2.2. -.IP 5. 5 -When the argument list is set up, create the widget with the -\fBXtCreateManagedWidget\fP function. For further information, see -Section 2.2 and the \fI\*(xT\fP. -.IN "XtCreateManagedWidget" -.IP 6. 5 -If the widget has any callback routines, set by the -.PN XtNcallback -argument or the -.PN XtAddCallback -function, declare these routines within the application. -.IN "XtAddCallback" -.IP 7. 5 -After creating the initial widget hierarchy, windows must be created -for each widget by calling -.PN XtRealizeWidget -on the top level widget. -.IN "XtRealizeWidget" -.IP 8. 5 -Most applications now sit in a loop processing events using -.PN XtAppMainLoop , -for example: -.IN "XtAppMainLoop" -.IP -.Ds 0 -XtCreateManagedWidget(\fIname\fP, \fIclass\fP, \fIparent\fP, \fIargs\fP, \fInum_args\fP); -XtRealizeWidget(\fIshell\fP); -XtAppMainLoop(\fIapp_context\fP); -.De -.IP -For information about this function, see the \fI\*(xT\fP. -.IP 9. 5 -Link your application with -.PN libXaw -(the Athena widgets), -.PN libXmu -(miscellaneous utilities), -.PN libXt -(the \*(tk \*(xI), -.PN libSM -(Session Management), -.PN libICE -(Inter-Client Exchange), -.PN libXext -(the extension library needed for the shape extension code which allows -rounded Command buttons), and -.PN libX11 -(the core X library). -The following provides a sample command line: -.IN "libXaw" -.IN "libXmu" -.IN "libXt" -.IN "libSM" -.IN "libICE" -.IN "libXext" -.IN "libX11" -.IN "linking applications" -.IN "compiling applications" -.IP -.Ds 0 -cc -o \fIapplication\fP \fIapplication\fP.c \-lXaw \-lXmu \-lXt \ -\-lSM \-lICE \-lXext \-lX11 -.De -.NH 3 -Changing Resource Values -.IN "resource" "" -.LP -The \*(xI support two methods of changing the default resource -values; the resource manager, and an argument list passed into -XtCreateWidget. While resources values will get updated no matter -which method you use, the two methods provide slightly different -functionality. -.IP "Resource Manager" 1.5i -This method picks up resource definitions described in \fI\*(xL\fP from -many different locations at run time. The locations most important to -the application programmer are the \fIfallback resources\fP and the -\fIapp-defaults\fP file, (see \fI\*(xT\fP for the complete list). -Since these resource are loaded at run time, they can be overridden by -the user, allowing an application to be customized to fit the -particular needs of each individual user. These values can also be -modified without the need to rebuild the application, allowing rapid -prototyping of user interfaces. Application programmers should use -resources in preference to hard-coded values whenever possible. -.IP "Argument Lists" 1.5i -The values passed into the widget at creation time via an argument list -cannot be modified by the user, and allow no opportunity for -customization. It is used to set resources that cannot be specified as -strings (e.g. callback lists) or resources that should not be -overridden (e.g. window depth) by the user. -.NH 4 -Specifying Resources -.LP -It is important for all X Toolkit application programmers to -understand how to use the X Resource Manager to specify resources for -widgets in an X application. This section will describe the most common -methods used to specify these resources, and how to use the X Resource -manager. -.IN "xrdb" -.IP \fBXrdb\fP 1.5i -The \fBxrdb\fP utility may be used to load a file containing -resources into the X server. Once the resources are loaded, the -resources will affect any new applications started on the display that -they were loaded onto. -.IN "application defaults" -.IN "app-defaults" -.IN "/usr/lib/X11/app-defaults" -.IP "\fBApplication Defaults\fP" 1.5i -The application defaults (app-defaults) file (normally in -/usr/lib/X11/app-defaults/\fIclassname\fP) for an application is loaded -whenever the application is started. -.LP -The resource specification has two colon-separated parts, a name, and -a value. The \fIvalue\fP is a string whose format is dependent on the -resource specified by \fIname\fP. \fIName\fP is constructed by -appending a resource name to a full widget name. -.LP -The full widget name is a list of the name of every ancestor of the -desired widget separated by periods (.). Each widget also has a class -associated with it. A class is a type of widget (e.g. Label or -Scrollbar or Box). Notice that class names, by convention, begin with -capital letters and instance names begin with lower case letters. The -class of any widget may be used in place of its name in a resource -specification. Here are a few examples: -.IP xman.form.button1 1.5i -This is a fully specified resource name, and will affect only widgets -called button1 that are children of widgets called form that are -children of -applications named xman. (Note that while typically two widgets that -are siblings will have different names, it is not prohibited.) - -.IP Xman.Form.Command 1.5i -This will match any Command widget that is a child of a Form widget -that is itself a child of an application of class \fIXman\fP. -.IP Xman.Form.button1 1.5i -This is a mixed resource name with both widget names and classes specified. -.LP -This syntax allows an application programmer to specify any widget -in the widget tree. To match more than one widget (for example a user -may want to make all Command buttons blue), use an asterisk (*) -instead of a period. When an asterisk is used, any number of widgets -(including zero) may exist between the two widget names. For example: -.IP Xman*Command 1.5i -This matches all Command widgets in the Xman application. -.IP Foo*button1 1.5i -This matches any widget in the Foo application that is named \fIbutton1\fP. -.LP -The root of all application widget trees is the widget returned by -\fBXtAppInitialize\fP. Even though this is actually an -ApplicationShell widget, the toolkit replaces its widget class with the -class name of the application. The name of this widget is either -the name used to invoke the application (\fBargv[0]\fP) or the name of -the application specified using the standard \fI-name\fP command line -option supported by the \*(xI. -.LP -The last step in constructing the resource name is to append the name of -the resource with either a period or asterisk to the full or partial -widget name already constructed. -.IP *foreground:Blue 2.25i -Specifies that all widgets in all applications will have a foreground -color of blue. -.IP Xman*borderWidth:10 2.25i -Specifies that all widgets in an application whose class is Xman will -have a border width of 10 (pixels). -.IP xman.form.button1.label:Testing 2.25i -Specifies that a particular widget in the xman application will have a -label named \fITesting\fP. -.LP -An exclamation point (!) in the first column of a line indicates -that the rest of the line should be treated as a comment. -.LP -\fBFinal Words\fP -.LP -The Resource manager is a powerful tool that can be used very -effectively to customize \*(tk applications at run time by either the -application programmer or the user. Some final points to note: -.IP \(bu 5 -An application programmer may add new resources to their -application. These resources are associated with the global -application, and not any particular widget. The \*(tk function used for -adding the application resources is \fBXtGetApplicationResources\fP. -.IN "XtGetApplicationResources" -.IP \(bu 5 -Be careful when creating resource files. Since widgets will -ignore resources that they do not understand, any spelling -errors will cause a resource to have no effect. -.IP \(bu 5 -Only one resource line will match any given resource. There is a set -of precedence rules, which take the following general stance. -.ta 10n -.IP "" 5 -\(bu More specific overrides less specific, thus period always overrides asterisk. -.IP "" 5 -\(bu Names on the left are more specific and override names on the right. -.IP "" 5 -\(bu When resource specifications are exactly the same, user defaults -.br - will override program defaults. -.LP -For a complete explanation of the rules of precedence, and -other specific topics see \fI\*(xT\fP and \fI\*(xL\fP. -.NH 4 -Creating Argument Lists -.IN "argument lists" "" "@DEF@" -.LP -To set up an argument list for the inline specification of widget attributes, -you may use any of the four approaches discussed in this section. -Each resource name has a global symbol associated with it. This -global symbol has the form XtN\fIresource name\fP. For example, the -symbol for ``foreground'' is \fBXtNforeground\fP. For further information, -see the \fI\*(xT\fP. -.LP -Argument are specified by using the following structure: -.IN "ArgList" "" "@DEF@" -.IN "Arg" "" "@DEF@" -.LP -.Ds 0 -.TA .5i 1.5i -.ta .5i 1.5i -typedef struct { - String name; - XtArgVal value; -} Arg, *ArgList; -.De -.LP -The first approach is to statically initialize the argument list. -For example: -.LP -.Ds 0 -.TA .5i -.ta .5i -static Arg arglist[] = { - {XtNwidth, (XtArgVal) 400}, - {XtNheight, (XtArgVal) 300}, -}; -.De -.LP -This approach is convenient for lists that do not need to be computed -at runtime and makes adding or deleting new elements easy. -The -.IN "XtNumber" -.PN XtNumber -macro is used to compute the number of elements in the argument list, -preventing simple programming errors: -.LP -.Ds -XtCreateWidget(\fIname\fP, \fIclass\fP, \fIparent\fP, \fIarglist\fP, XtNumber(\fIarglist\fP)); -.De -.IN "XtSetArg" "" "@DEF@" -.LP -The second approach is to use the -.PN XtSetArg -macro. -For example: -.LP -.Ds 0 -.TA .5i -.ta .5i -Arg arglist[10]; -XtSetArg(arglist[1], XtNwidth, 400); -XtSetArg(arglist[2], XtNheight, 300); -.De -.LP -To make it easier to insert and delete entries, -you also can use a variable index: -.LP -.Ds 0 -.TA .5i -.ta .5i -Arg arglist[10]; -Cardinal i=0; -XtSetArg(arglist[i], XtNwidth, 400); i++; -XtSetArg(arglist[i], XtNheight, 300); i++; -.De -.LP -The i variable can then be used as the argument list count in the widget -create function. -In this example, -.IN "XtNumber" -.PN XtNumber -would return 10, not 2, and therefore is not useful. -.NT -You should not use auto-increment or auto-decrement -within the first argument to -.PN XtSetArg . -As it is currently implemented, -.PN XtSetArg -is a macro that dereferences the first argument twice. -.NE -.LP -The third approach is to individually set the elements of the -argument list array: -.LP -.Ds 0 -.TA .5i -.ta .5i -Arg arglist[10]; -arglist[0].name = XtNwidth; -arglist[0].value = (XtArgVal) 400; -arglist[1].name = XtNheight; -arglist[1].value = (XtArgVal) 300; -.De -.LP -Note that in this example, as in the previous example, -.IN "XtNumber" -.PN XtNumber -would return 10, not 2, and therefore would not be useful. -.LP -The fourth approach is to use a mixture of the first and third approaches: -you can statically define the argument list but modify some entries at runtime. -For example: -.LP -.Ds 0 -.TA .5i -.ta .5i -static Arg arglist[] = { - {XtNwidth, (XtArgVal) 400}, - {XtNheight, (XtArgVal) NULL}, -}; -arglist[1].value = (XtArgVal) 300; -.De -.LP -In this example, -.IN "XtNumber" -.PN XtNumber -can be used, as in the first approach, for easier code maintenance. -.NH 2 -Example Programs -.XS - Example Programs -.XE -.IN "examples" -.LP -The best way to understand how to use any programming library is by -trying some simple examples. A collection of example programs that -introduces each of the widgets in that Athena widget set, as well as many -important toolkit programming concepts, is available in the X11R6 -release as distributed by the X Consortium. It can be found in the -distribution directory \fBcontrib/examples/mit/Xaw\fP, but see your -site administrator for the exact location of these files on your system. -See the README file from that directory for a guide to the examples. - diff --git a/xc/doc/specs/Xaw/CH3.intro b/xc/doc/specs/Xaw/CH3.intro deleted file mode 100644 index 9040e02d5..000000000 --- a/xc/doc/specs/Xaw/CH3.intro +++ /dev/null @@ -1,67 +0,0 @@ -.bp -.if e .bp \" make sure we break on an odd page. -\& -.sp 1 -.ce 3 -\s+1\fBChapter 3\fP\s-1 - -\s+1\fBSimple Widgets\fP\s-1 -.IN "simple widgets" "" -.sp 2 -.nr H1 3 -.nr H2 0 -.nr H3 0 -.nr H4 0 -.nr H5 0 -.na -.LP -.XS -Chapter 3 - Simple Widgets -.XE -.LP -Each of these widgets performs a specific user interface function. They -are \fIsimple\fP because they cannot have widget children\(emthey may only -be used as leaves of the widget tree. These widgets display information or -take user input. -.sp -.IP \fBCommand\fP 1i -.IN "Command widget" "" -A push button that, when selected, may cause a specific action -to take place. This widget can display a multi-line string or a bitmap or pixmap image. -.IP \fBGrip\fP 1i -.IN "Grip widget" "" -A rectangle that, when selected, will cause an action to take place. -.IP \fBLabel\fP 1i -.IN "Label widget" "" -A rectangle that can display a multi-line string or a bitmap or pixmap image. -.IP \fBList\fP 1i -.IN "List widget" "" -A list of text strings presented in row column format that may be -individually selected. When an element is selected an action may take -place. -.IP \fBPanner\fP 1i -.IN "Panner widget" "" -A rectangular area containing a \fIslider\fP that may be moved in two -dimensions. Notification of movement may be continuous or discrete. -.IP \fBRepeater\fP 1i -.IN "Repeater widget" "" -A push button that triggers an action at an increasing rate when selected. -This widget can display a multi-line string or a bitmap or pixmap image. -.IP \fBScrollbar\fP -.IN "Scrollbar widget" "" -A rectangular area containing a \fIthumb\fP that when slid along one -dimension may cause a specific action to take place. The Scrollbar may -be oriented horizontally or vertically. -.IP \fBSimple\fP 1i -.IN "Simple widget" "" -The base class for most of the simple widgets. Provides a rectangular -area with a settable mouse cursor and special border. -.IP \fBStripChart\fP 1i -.IN "StripChart widget" "" -A real time data graph that will automatically update and scroll. -.IP \fBToggle\fP 1i -.IN "Toggle widget" "" -A push button that contains state information. Toggles -may also be used as ``radio buttons'' to implement a ``one of many'' or -``zero or one of many'' group -of buttons. This widget can display a multi-line string or a bitmap or pixmap image. diff --git a/xc/doc/specs/Xaw/CH4.intro b/xc/doc/specs/Xaw/CH4.intro deleted file mode 100644 index c11e42547..000000000 --- a/xc/doc/specs/Xaw/CH4.intro +++ /dev/null @@ -1,87 +0,0 @@ -.bp -\& -.sp 1 -.ce 3 -\s+1\fBChapter 4\fP\s-1 - -\s+1\fBMenus\fP\s-1 -.sp 2 -.nr H1 4 -.nr H2 0 -.nr H3 0 -.nr H4 0 -.nr H5 0 -.na -.LP -.XS -Chapter 4 - Menus -.XE -.IN "Menus" "" -.LP -The Athena widget set provides support for single paned non-hierarchical -popup and pulldown menus. Since menus are such a common user interface -tool, support for them must be provided in even the most basic widget -sets. In menuing as in other areas, the Athena Widget Set provides only -basic functionality. -.LP -Menus in the Athena widget set are implemented as a menu container (the -SimpleMenu widget) and a collection of objects that comprise the -menu entries. The SimpleMenu widget is itself a direct subclass of the -OverrideShell widget class, so no other shell is necessary when -creating a menu. The managed children of a SimpleMenu must be -subclasses of the Sme (Simple Menu Entry) object. -.LP -The Athena widget set provides three classes of Sme objects that may be -used to build menus. -.sp -.IP \fBSme\fP 1i -.IN "Sme object" "" -The base class of all menu entries. It may be used as a menu entry -itself to provide blank space in a menu. ``Sme'' means ``Simple Menu -Entry.'' -.IP \fBSmeBSB\fP 1i -.IN "SmeBSB object" "" -This menu entry provides a selectable entry containing a text string. -A bitmap may also be placed in the left and right margins. ``BSB'' means -``Bitmap String Bitmap.'' -.IP \fBSmeLine\fP 1i -.IN "SmeLine object" "" -This menu entry provides an unselectable entry containing a separator line. -.sp -.LP -The SimpleMenu widget informs the window manager that it should ignore -its window by setting the \fBOverride Redirect\fP flag. This is the -correct behavior for the press-drag-release style of menu operation. If -click-move-click or ``pinable''' menus are desired it is the -responsibility of the application programmer, using the SimpleMenu -resources, to inform the window manager of the menu. -.LP -To allow easy creation of pulldown menus, a MenuButton widget is -also provided as part of the Athena widget set. -.NH 2 -Using the Menus -.XS - Using the Menus -.XE -.IN "Menus" "using" -.LP -The default configuration for the menus is press-drag-release. -The menus will typically be -activated by clicking a pointer button while the pointer is over a -MenuButton, causing the menu to appear in a fixed location relative to -that button; this is a \fBpulldown\fP menu. Menus may also be activated -.IN "Menus" "pulldown" -when a specific pointer and/or key sequence is used anywhere in the -application; this is a \fBpopup\fP menu (e.g. clicking Ctrl-<pointer -.IN "Menus" "popup" -button 1> in the common application \fBxterm\fP). In this -case the menu should be positioned under -the cursor. Typically menus will be placed so the pointer cursor is on -the first menu entry, or the last entry selected by the user. -.LP -The menu remains on the screen as long as the pointer button is held -down. Moving the pointer will highlight different menu items. -If the pointer leaves the menu, or moves over an entry that cannot -be selected then no menu entry will highlighted. When the desired menu -entry has been highlighted, releasing the pointer button removes the menu, -and causes any mechanism associated with this entry to be invoked. diff --git a/xc/doc/specs/Xaw/CH5.intro b/xc/doc/specs/Xaw/CH5.intro deleted file mode 100644 index 0181d81f1..000000000 --- a/xc/doc/specs/Xaw/CH5.intro +++ /dev/null @@ -1,292 +0,0 @@ -.\" $XConsortium: CH5.intro,v 1.20 94/05/01 19:24:33 gildea Exp $ -.LP -.bp -\& -.sp 1 -.ce 3 -\s+1\fBChapter 5\fP\s-1 - -\s+1\fBText Widgets\fP\s-1 -.sp 2 -.nr H1 5 -.nr H2 0 -.nr H3 0 -.nr H4 0 -.nr H5 0 -.na -.LP -.XS -Chapter 5 - Text Widgets. -.XE -.LP -The Text widget provides a window that will allow an application -to display and edit one or more lines of text. Options are provided to -allow the user to add Scrollbars to its window, search for a specific -string, and modify the text in the buffer. -.LP -The Text widget is made up of a number of pieces; it was modularized to -ease customization. The AsciiText widget class (actually not limited to -ASCII but so named for compatibility) is be general enough to most -needs. If more flexibility, special features, or extra functionality is -needed, they can be added by implementing a new TextSource or TextSink, or -by subclassing the Text Widget (See Section 5.8 for customization -details.) -.LP -The words \fIinsertion point\fP are used in this chapter to refer to the text -caret. This is the symbol that is displayed between two characters in -the file. The insertion point marks the location where any new characters -will be added to the file. To avoid confusion the pointer cursor will -always be referred to as the \fIpointer\fP. -.LP -The text widget supports three edit modes, controlling the types of -modifications a user is allowed to make: -.IN "Text widget" "edit modes" -.IP \(bu 5 -Append-only -.IP \(bu 5 -Editable -.IP \(bu 5 -Read-only -.LP -Read-only mode does not allow the user or the programmer to modify the text -in the widget. While the entire string may be reset in -read-only mode with \fBXtSetValues\fP, it cannot be modified via -with \fBXawTextReplace\fP. Append-only and editable modes allow -.IN "XawTextReplace" "" -the text at the insertion point to be modified. The only difference is -that text may only be added to or removed from the end of a buffer in -append-only mode. -.LP -.NH 2 -Text Widget for Users -.IN "Text widget" "User's Guide to the Text widget" -.XS - Text Widget for Users -.XE -.LP -The Text widget provides many of the common keyboard editing commands. -These commands allow users to move around and edit the buffer. If an -illegal operation is attempted, (such as deleting characters in a -read-only text widget), the X server will beep. -.NH 3 -Default Key Bindings -.IN "Text widget" "default key bindings" -.LP -The default key bindings are patterned after those in the EMACS text editor: -.sp -.Ds 0 -.TA 1.0i 3.0i 4.5i -.ta 1.0i 3.0i 4.5i -Ctrl-a Beginning Of Line Meta-b Backward Word -Ctrl-b Backward Character Meta-f Forward Word -Ctrl-d Delete Next Character Meta-i Insert File -Ctrl-e End Of Line Meta-k Kill To End Of Paragraph -Ctrl-f Forward Character Meta-q Form Paragraph -Ctrl-g Multiply Reset Meta-v Previous Page -Ctrl-h Delete Previous Character Meta-y Insert Current Selection -Ctrl-j Newline And Indent Meta-z Scroll One Line Down -Ctrl-k Kill To End Of Line Meta-d Delete Next Word -Ctrl-l Redraw Display Meta-D Kill Word -Ctrl-m Newline Meta-h Delete Previous Word -Ctrl-n Next Line Meta-H Backward Kill Word -Ctrl-o Newline And Backup Meta-< Beginning Of File -Ctrl-p Previous Line Meta-> End Of File -Ctrl-r Search/Replace Backward Meta-] Forward Paragraph -Ctrl-s Search/Replace Forward Meta-[ Backward Paragraph -Ctrl-t Transpose Characters -Ctrl-u Multiply by 4 Meta-Delete Delete Previous Word -Ctrl-v Next Page Meta-Shift Delete Kill Previous Word -Ctrl-w Kill Selection Meta-Backspace Delete Previous Word -Ctrl-y Unkill Meta-Shift Backspace Kill Previous Word -Ctrl-z Scroll One Line Up -Ctrl-\\ Reconnect to input method -Kanji Reconnect to input method -.De -.sp -.LP -In addition, the pointer may be used to cut and paste text: -.LP -.Ds -.TA .5i 2.0i -.ta .5i 2.0i - Button 1 Down Start Selection - Button 1 Motion Adjust Selection - Button 1 Up End Selection (cut) - - Button 2 Down Insert Current Selection (paste) - - Button 3 Down Extend Current Selection - Button 3 Motion Adjust Selection - Button 3 Up End Selection (cut) - -.De -.LP -Since all of these key and pointer bindings are set through the -translations and resource manager, the user and the application -programmer can modify them by changing the Text widget's -\fBtranslations\fP resource. -.\" -.NH 3 -Search and Replace -.IN "Text widget" "search" -.IN "Text widget" "query replace" -.LP -The Text widget provides a search popup that can be used to search for a -string within the current Text widget. The popup can be activated by -typing either \fIControl-r\fP or \fIControl-s\fP. If \fIControl-s\fP is -used the search will be forward in the file from the current location of the -insertion point; if \fIControl-r\fP is used the search will be backward. The -activated popup is placed under the pointer. It has a number of buttons -that allow both text searches and text replacements to be performed. -.LP -At the top of the search popup are two toggle buttons labeled -\fIbackward\fP and \fIforward\fP. One of these buttons will always be -highlighted; this is the direction in which the search will be -performed. The user can change the direction at any time by clicking on -the appropriate button. -.LP -Directly under the buttons there are two text areas, one labeled -\fISearch for:\fP and the other labeled \fIReplace with:\fP. If this is -a read-only Text widget the \fIReplace with:\fP field will be insensitive -and no replacements will be allowed. After each of these labels will be -a text field. This field will allow the user to enter a string to -search for and the string to replace it with. Only one of these text -fields will have a window border around it; this is the active text -field. Any key presses that occur when the focus in in the search popup -will be directed to the active text field. There are also a few special -key sequences: -.DS -.TA 1.75i -.ta 1.75i -\fBCarriage Return\fP: Execute the action, and pop down the search widget. -\fBTab\fP: Execute the action, then move to the next field. -\fBShift Carriage Return\fP: Execute the action, then move to the next field. -\fBControl-q Tab\fP: Enter a Tab into a text field. -\fBControl-c\fP: Pop down the search popup. -.DE -.LP -Using these special key sequences should allow simple -searches without ever removing one's hands from the keyboard. -.LP -Near the bottom of the search popup is a row of buttons. These buttons -allow the same actions to to be performed as the key sequences, but the -buttons will leave the popup active. This can be quite useful if many -searches are being performed, as the popup will be left on the display. -Since the search popup is a transient window, it may be picked -up with the window manager and pulled off to the side for use -at a later time. -.IP \fBSearch\fP 15 -Search for the specified string. -.IP \fBReplace\fP 15 -Replace the currently highlighted string with the string in the -\fIReplace with\fP text field, and move onto the next occurrence of the -\fISearch for\fP text field. The functionality is commonly referred to as -query-replace. -.IP \fBReplace-All\fP 15 -Replace all occurrences of the search string with the replace string from -the current insertion point position to the end (or beginning) of the -file. There is no key sequence to perform this action. -.IP \fBCancel\fP 15 -Remove the search popup from the screen. -.LP -Finally, when \fBinternational\fP resource is \fBtrue\fP, there may be a -pre-edit buffer below the button row, for composing input. Its presence -is determined by the X locale in use and the VendorShell's \fBpreeditType\fP -resource. -.LP -The widget hierarchy for the search popup is show below, all widgets -are listed by class and instance name. -.sp -.nf -.ta .5i 1.0i 1.5i 2.0i 2.5i -Text <name of Text widget> - TransientShell search - Form form - Label label1 - Label label2 - Toggle backwards - Toggle forwards - Label searchLabel - Text searchText - Label replaceLabel - Text replaceText - Command search - Command replaceOne - Command replaceAll - Command cancel -.fi -.NH 3 -File Insertion -.LP -.IN "Text widget" "file insertion" -To insert a file into a text widget, type the key sequence \fIMeta-i\fP, -which will activate the file insert popup. This popup will appear under -the pointer, and any text typed while the focus is in this popup will be -redirected to the text field used for the filename. When the desired -filename has been entered, click on \fIInsert File\fP, or type -\fICarriage Return\fP. The named file will then be inserted in the text -widget beginning at the insertion point position. If an error occurs when -opening the file, an error message will be printed, prompting the user -to enter the filename again. The file insert may be aborted by clicking -on \fICancel\fP. If \fIMeta-i\fP is typed at a text widget that is -read-only, it will beep, as no file insertion is allowed. -.LP -The widget hierarchy for the file insert popup is show below; all widgets -are listed by class and instance name. -.sp -.nf -.ta .5i 1.0i 1.5i 2.0i 2.5i -Text <name of Text widget> - TransientShell insertFile - Form form - Label label - Text text - Command insert - Command cancel -.fi -.NH 3 -Text Selections for Users -.LP -.IN "Text widget" "Text Selections for Users" -The text widgets have a text selection mechanism that allows -the user to copy pieces of the text into the \fBPRIMARY\fP selection, -and paste -into the text widget some text that another application (or text -widget) has put in the \fBPRIMARY\fP selection. -.LP -One method of selecting text is to press pointer button 1 -on the beginning of the text to be selected, drag the pointer until all -of the desired text is highlighted, and then release the button to -activate the selection. Another method is to click pointer button 1 at -one end of the text to be selected, then click pointer button 3 at the -other end. -.LP -To modify a currently active selection, press pointer button 3 near -either the end of the selection that you want to -adjust. This end of the selection may be moved while holding down pointer -button 3. When the proper area has been highlighted release the pointer -button to activate the selection. -.LP -The selected text may now be pasted into another application, and -will remain active until some other client makes a selection. -To paste text that some other application has -put into the \fBPRIMARY\fP selection use pointer button 2. -First place the insertion point where you would like the text to be inserted, -then click and release pointer button 2. -.LP -Rapidly clicking pointer button 1 the following number of times will adjust -the selection as described. -.IP \fBTwo\fP 1.0i -Select the word under the pointer. A word boundary is defined by the -Text widget to be a Space, Tab, or Carriage Return. -.IP \fBThree\fP 1.0i -Select the line under the pointer. -.IP \fBFour\fP 1.0i -Select the paragraph under the pointer. A paragraph boundary is -defined by the text widget as two Carriage Returns in a row with only -Spaces or Tabs between them. -.IP \fBFive\fP 1.0i -Select the entire text buffer. -.LP -To unset the text selection, click pointer button 1 -without moving it. diff --git a/xc/doc/specs/Xaw/CH6.intro b/xc/doc/specs/Xaw/CH6.intro deleted file mode 100644 index 655cf635a..000000000 --- a/xc/doc/specs/Xaw/CH6.intro +++ /dev/null @@ -1,84 +0,0 @@ -.LP -.bp -.if e .bp \" make sure we break on an odd page. -\& -.sp 1 -.ce 3 -\s+1\fBChapter 6\fP\s-1 - -\s+1\fBComposite and Constraint Widgets\fP\s-1 -.sp 2 -.nr H1 6 -.nr H2 0 -.nr H3 0 -.nr H4 0 -.nr H5 0 -.na -.LP -.XS -Chapter 6 - Composite and Constraint Widgets -.XE -.LP -These widgets may contain arbitrary widget children. They implement a -policy for the size and location of their children. -.IP \fBBox\fP 1i -.IN "Box widget" "" -This widget will pack its children as tightly as possible in -non-overlapping rows. -.IP \fBDialog\fP 1i -.IN "Dialog widget" "" -An implementation of a commonly used interaction semantic to prompt for -auxiliary input from the user, such as a filename. -.IP \fBForm\fP 1i -.IN "Form widget" "" -A more sophisticated layout widget that allows the children to specify -their positions relative to the other children, or to the edges of the Form. -.IP \fBPaned\fP 1i -.IN "Paned widget" "" -Allows children to be tiled vertically or horizontally. Controls are -also provided to allow the user to dynamically resize the individual panes. -.IP \fBPorthole\fP 1i -.IN "Porthole widget" "" -Allows viewing of a managed child which is as large as, or larger than its -parent, typically under control of a Panner widget. -.IP \fBTree\fP 1i -.IN "Tree widget" "" -Provides geometry management of widgets arranged in a directed, acyclic graph. -.IP \fBViewport\fP 1i -.IN "Viewport widget" "" -Consists of a frame, one or two scrollbars, and an inner window. The -inner window can contain all the data that is to be displayed. This inner -window will be clipped by the frame with the scrollbars controlling -which section of the inner window is currently visible. -.LP -.NH 3 -A Brief Note on Geometry Management -.IN "geometry management" "" -.LP -The geometry management semantics provided by the X Toolkit give full -control of the size and position of a widget to the parent of that -widget. While the children are allowed to request a certain size or -location, it is the parent who makes the final decision. Many of the -composite widgets here will deny any geometry request from their -children by default. If a child widget is not getting the expected size -or location, it is most likely the parent disallowing a request, or -implementing semantics slightly different than those expected by the -application programmer. -.LP -If the application wishes to change the size or location of -any widget it should make a call to \fBXtSetValues\fP. This will -.IN "XtSetValues" "" -allow the widget to ask its parent for the new size or location. -As noted above the parent is allowed to refuse this request, -and the child must live with the result. If the -application is unable to achieve the desired semantics, then perhaps it -should use a different composite widget. Under no circumstances -should an application programmer resort to \fBXtMoveWidget\fP or -.IN "XtMoveWidget" "" -\fBXtResizeWidget\fP; these functions are exclusively for the use of -.IN "XtResizeWidget" "" -Composite widget implementors. -.LP -For more information on geometry management consult the \fI\*(xT\fP. - - diff --git a/xc/doc/specs/Xaw/CH7.intro b/xc/doc/specs/Xaw/CH7.intro deleted file mode 100644 index 7aaa1896b..000000000 --- a/xc/doc/specs/Xaw/CH7.intro +++ /dev/null @@ -1,99 +0,0 @@ -.LP -.bp -.if e .bp \" make sure we break on an odd page. -\& -.sp 1 -.ce 5 -\s+1\fBChapter 7\fP\s-1 - -\s+1\fBCreating New Widgets (Subclassing)\fP\s-1 - -\s+1Written By: Ralph Swick\s-1 -.sp 2 -.nr H1 7 -.nr H2 0 -.nr H3 0 -.nr H4 0 -.nr H5 0 -.na -.LP -.XS -Chapter 7 - Creating New Widgets (Subclassing) -.XE -.IN "subclassing" "" "@DEF@" -.IN "creating new widgets" "" "@DEF@" -.LP -Although the task of creating a new widget may at first appear a little -daunting, there is a basic simple pattern that all widgets follow. The -Athena Widget library contains a special widget called the -\fITemplate\fP widget that is intended to assist the novice widget -programmer in writing a custom widget. -.LP -Reasons for wishing to write a custom widget include: -.IP \(bu 3 -Providing a graphical interface not currently supported by any existing -widget set. -.IP \(bu 3 -Convenient access to resource management procedures to obtain fonts, -colors, etc., even if user customization is not desired. -.IP \(bu 3 -Convenient access to user input dispatch and translation management procedures. -.IP \(bu 3 -Access to callback mechanism for building higher-level application libraries. -.IP \(bu 3 -Customizing the interface or behavior of an existing widget to suit a -special application need. -.IP \(bu 3 -Desire to allow user customization of resources such as fonts, colors, -etc., or to allow convenient re-binding of keys and buttons to internal -functions. -.IP \(bu 3 -Converting a non-Toolkit application to use the Toolkit. -.LP -In each of these cases, the operation needed to create a new widget is -to "subclass" an existing one. If the desired semantics of the new -widget are similar to an existing one, then the implementation of the -existing widget should be examined to see how much work would be -required to create a subclass that will then be -able to share the existing class methods. Much time will be saved in -writing the new widget if an existing widget class Expose, Resize and/or -GeometryManager method can be used by the subclass. -.LP -Note that some trivial uses of a ``bare-bones'' widget may be achieved by -simply creating an instance of the Core -widget. The class variable to use when creating a Core widget is -.PN widgetClass . -The geometry of the Core widget is determined entirely by the parent -widget. -.LP -It is very often the case than an application will have a special need -for a certain set of functions and that many copies of these functions -will be needed. For example, when converting an older application to use -the Toolkit, it may be desirable to have a "Window Widget" class that -might have the following semantics: -.IN "Window widget" -.IN "Core widget" -.IN "widgetClass" -.IP \(bu 3 -Allocate 2 drawing colors in addition to a background color. -.IP \(bu 3 -Allocate a text font. -.IP \(bu 3 -Execute an application-supplied function to handle exposure events. -.IP \(bu 3 -Execute an application-supplied function to handle user input events. -.LP -It is obvious that a completely general-purpose WindowWidgetClass could -be constructed that would export all class methods as callbacks lists, -but such a widget would be very large and would have to choose some -arbitrary number of resources such as colors to allocate. An application -that used many instances of the general-purpose widget would therefore -un-necessarily waste many resources. -.LP -.sp -In this section, an outline will be given of the procedure to follow to -construct a special-purpose widget to address the items listed above. -The reader should refer to the appropriate sections of the \fI\*(xT\fP -for complete details of the material outlined here. Section 1.4 of -the \fI\*(xI\fP should be read in conjunction with this section. -.LP diff --git a/xc/doc/specs/Xaw/Command b/xc/doc/specs/Xaw/Command deleted file mode 100644 index 0e91e541d..000000000 --- a/xc/doc/specs/Xaw/Command +++ /dev/null @@ -1,205 +0,0 @@ -.\" $XConsortium: Command,v 1.23 94/05/01 19:21:05 gildea Exp $ -.NH 2 -Command Widget -.XS - Command Widget -.XE -.IN "Command widget" "" "@DEF@" -.Ds 0 -.TA 2.0i -.ta 2.0i -.sp -Application header file <X11/Xaw/Command.h> -.IN "Command.h" "" -Class header file <X11/Xaw/CommandP.h> -.IN "CommandP.h" "" -Class commandWidgetClass -.IN "commandWidgetClass" "" -Class Name Command -.IN "Command widget" "class name" -Superclass Label -.sp -.De -.LP -The Command widget is an area, often rectangular, that contains text -or a graphical image. Command widgets are often referred to as -``push buttons.'' When the pointer is over a Command widget, the -widget becomes highlighted by drawing a rectangle around its perimeter. -This highlighting indicates that the widget is ready for selection. -When mouse button 1 is pressed, the Command widget indicates that -it has been selected by reversing its foreground and background colors. -When the mouse button is released, the Command widget's \fBnotify\fP -action is invoked, calling all functions on its callback list. If -the pointer is moved off of the widget before the pointer button is -released, the widget reverts to its normal foreground and background -colors, and releasing the pointer button has no effect. This behavior -allows the user to cancel an action. -.NH 3 -Resources -.LP -When creating a Command widget instance, the following resources are -retrieved from the argument list or from the resource database: -.LP -.IN "Command 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 -bitmap Bitmap Pixmap None -borderColor BorderColor Pixel XtDefaultForeground -borderPixmap Pixmap Pixmap XtUnspecifiedPixmap -borderWidth BorderWidth Dimension 1 -callback Callback XtCallbackList NULL -colormap Colormap Colormap Parent's Colormap -cornerRoundPercent CornerRoundPercent Dimension 25 -cursor Cursor Cursor None -cursorName Cursor String NULL -depth Depth int C Parent's Depth -destroyCallback Callback XtCallbackList NULL -encoding Encoding UnsignedChar XawTextEncoding8bit -font Font XFontStruct XtDefaultFont -foreground Foreground Pixel XtDefaultForeground -height Height Dimension A graphic height + 2 * \fBinternalHeight\fP -highlightThickness Thickness Dimension A 2 (0 if Shaped) -insensitiveBorder Insensitive Pixmap GreyPixmap -internalHeight Height Dimension 2 -internalWidth Width Dimension 4 -international International Boolean C False -justify Justify Justify XtJustifyCenter (center) -label Label String name of widget -leftBitmap LeftBitmap Bitmap None -mappedWhenManaged MappedWhenManaged Boolean True -pointerColor Foreground Pixel XtDefaultForeground -pointerColorBackground Background Pixel XtDefaultBackground -resize Resize Boolean True -screen Screen Screen R Parent's Screen -sensitive Sensitive Boolean True -shapeStyle ShapeStyle ShapeStyle Rectangle -translations Translations TranslationTable See below -width Width Dimension A graphic width + 2 * \fBinternalWidth\fP -x Position Position 0 -y Position Position 0 -.sp 3p -_ -.TE -\" Resource Descriptions -.Ac -.As -.Bg -.Gp -.Bm -.Bc -.Bp -.Bw -.Cb Bold -.Cm -.Cr Bold -.Cu -.Cn -.Dp -.Dc -.Le -.Lf -.Ls -.Lg -.Hw -.Ht Bold -.Ib -.Ih -.In -.Ju -.La -.Ll -.Mm -.Pf -.Pb -.Re -.Sc -.Se -.Ss Bold -.Tr -.Xy -.NH 3 -Command Actions -.IN "Command widget" "actions" -.LP -The Command widget supports the following actions: -.IP \(bu 5 -Switching the button's interior between the foreground and background -colors with \fBset\fP, \fBunset\fP, and \fBreset\fP. -.IP \(bu 5 -Processing application callbacks with \fBnotify\fP -.IP \(bu 5 -Switching the internal border between highlighted -and unhighlighted states with \fBhighlight\fP and \fBunhighlight\fP -.LP -.IN "Command widget" "translation bindings" -The following are the default translation bindings used by the -Command widget: -.LP -.Ds 0 -.TA .5i 2.25i -.ta .5i 2.25i - <EnterWindow>: highlight(\|) - <LeaveWindow>: reset(\|) - <Btn1Down>: set(\|) - <Btn1Up>: notify(\|) unset(\|) -.De -.LP -The full list of actions supported by Command is: -.IP \fBhighlight\fP(\fIcondition\fP) 1.5i -Displays the internal highlight border in the color (\fBforeground\fP -or \fBbackground\fP ) that contrasts with the interior color of the -Command widget. The conditions \fBWhenUnset\fP and \fBAlways\fP are -understood by this action procedure. If no argument is passed, -\fBWhenUnset\fP is assumed. -.IP \fBunhighlight\fP(\|) 1.5i -Displays the internal highlight border in the color (\fBforeground\fP -or \fBbackground\fP ) that matches the interior color of the -Command widget. -.IP \fBset\fP(\|) 1.5i -Enters the \fIset\fP state, in which \fBnotify\fP is possible. This -action causes the button to display its interior in the -\fBforeground\fP color. The label or bitmap is displayed in the -\fBbackground\fP color. -.IP \fBunset\fP(\|) 1.5i -Cancels the \fIset\fP state and displays the interior of the button in the -\fBbackground\fP color. The label or bitmap is displayed in the -\fBforeground\fP color. -.IP \fBreset\fP(\|) 1.5i -Cancels any \fIset\fP or \fIhighlight\fP and displays the interior of the -button in the \fBbackground\fP color, with the label or bitmap displayed -in the \fBforeground\fP color. -.IP \fBnotify\fP(\|) 1.5i -When the button is in the \fBset\fP state this action calls all functions in -the callback list named by the \fBcallback\fP resource. The value of -the \fIcall_data\fP argument passed to these functions is undefined. -.LP -A very common alternative to registering callbacks is to augment a -Command's translations with an action performing the desired -function. This often takes the form of: -.LP -.Ds 0 -.TA .5i 2.25i -.ta .5i 2.25i -*Myapp*save.translations: #augment <Btn1Down>,<Btn1Up>: Save() -.De -.LP -.NT -When a bitmap of depth greater that one (1) is specified the -\fIset\fP(), \fIunset\fP(), and \fIreset\fP() actions have no effect, -since there are no foreground and background colors used in a -multi-plane pixmap. -.NE diff --git a/xc/doc/specs/Xaw/Dialog b/xc/doc/specs/Xaw/Dialog deleted file mode 100644 index 04974e06b..000000000 --- a/xc/doc/specs/Xaw/Dialog +++ /dev/null @@ -1,280 +0,0 @@ -.\" $XConsortium: Dialog,v 1.17 94/05/01 20:44:56 gildea Exp $ -.NH 2 -Dialog Widget -.LP -.XS - Dialog Widget -.XE -.IN "Dialog widget" "" "@DEF@" -.Ds 0 -.TA 2.0i -.ta 2.0i -.sp -Application Header file <X11/Xaw/Dialog.h> -.IN "Dialog.h" "" -Class Header file <X11/Xaw/DialogP.h> -.IN "DialogP.h" "" -Class dialogWidgetClass -.IN "dialogWidgetClass" "" -Class Name Dialog -.IN "Dialog widget" "class name" -Superclass Form -.sp -.De -.LP -The Dialog widget implements a commonly used interaction semantic to -prompt for auxiliary input from a user. For example, you can use a -Dialog widget when an application requires a small piece of information, -such as a filename, from the user. A Dialog widget, which is simply a -special case of the Form widget, provides a convenient way to create a -preconfigured form. -.LP -The typical Dialog widget contains three areas. The first line -contains a description of the function of the Dialog widget, for -example, the string \fIFilename:\fP. The second line contains an area -into which the user types input. The third line can contain buttons -that let the user confirm or cancel the Dialog input. Any of these -areas may be omitted by the application. -.NH 3 -Resources -.LP -When creating a Dialog widget instance, the following resources are -retrieved from the argument list or the resource database: -.IN "Dialog 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 -defaultDistance Thickness int 4 -depth Depth int C Parent's Depth -destroyCallback Callback XtCallbackList NULL -height Height Dimension A Enough space to contain all children -icon Icon Bitmap None -label Label String "label" -mappedWhenManaged MappedWhenManaged Boolean True -numChildren ReadOnly Cardinal R 0 -screen Screen Screen R Parent's Screen -sensitive Sensitive Boolean True -translations Translations TranslationTable NULL -value Value String no value widget -width Width Dimension A Enough space to contain all children -x Position Position 0 -y Position Position 0 -.sp 3p -_ -.TE -.Ac -.As -.Bg -.Gp -.Bc -.Bp -.Bw -.Ch -.Cm -.Dd -.Dp -.Dc -.Hw -.IP \fBicon\fP 1.5i -A pixmap image to be displayed immediately to the left of the -Dialog widget's label. -.IP \fBlabel\fP 1.5i -A string to be displayed at the top of the Dialog widget. -.Mm -.Nc -.Sc -.Se -.Tr -.IP \fBvalue\fP 1.5i -An initial value for the string field that the user will enter text -into. By default, no text entry field is available to the user. -Specifying an initial value for \fBvalue\fP activates the text entry -field. If string input is desired, but no initial value is to be -specified then set this resource to "" (empty string). -.Xy -.NH 3 -Constraint Resources -.LP -.IN "Dialog widget" "constraint resources" -Each child of the Dialog widget may request special layout resources -be applied to it. These \fIconstraint\fP resources allow the Dialog -widget's children to specify individual layout requirements. -.LP -.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 -bottom Edge XawEdgeType XawRubber -fromHoriz Widget Widget NULL (left edge of Dialog) -fromVert Widget Widget NULL (top edge of Dialog) -horizDistance Thickness int \fBdefaultDistance\fP resource -left Edge XawEdgeType XawRubber -.IN "XawEdgeType" "" -resizable Boolean Boolean FALSE -right Edge XawEdgeType XawRubber -.IN "XawRubber" "" -top Edge XawEdgeType XawRubber -vertDistance Thickness int \fBdefaultDistance\fP resource -.sp 3p -_ -.TE -.Bt -.Fh -.Hd -.Rl -.NH 3 -Layout Semantics -.IN "Dialog widget" "layout semantics" -.LP -.Lt Dialog -.LP -.TS H -lw(1.5i) lw(1i) lw(3i). -_ -.sp 3p -.TB -Edge Type Resource Name Description -.sp 3p -_ -.TH -.R -.sp 3p -XawChainBottom ChainBottom Edge remains a fixed distance from bottom of Dialog -.IN "XawChainBottom" "" -XawChainLeft ChainLeft Edge remains a fixed distance from left of Dialog -.IN "XawChainLeft" "" -XawChainRight ChainRight Edge remains a fixed distance from right of Dialog -.IN "XawChainRight" "" -XawChainTop ChainTop Edge remains a fixed distance from top of Dialog -.IN "XawChainTop" "" -XawRubber Rubber Edges will move a proportional distance -.IN "XawRubber" "" -.sp 3p -_ -.TE -.NH 4 -Example -.LP -If you wish to force the Dialog to never resize one or more of its children -then set \fBleft\fP and \fBright\fP to \fBXawChainLeft\fP and -\fBtop\fP and \fBbottom\fP to \fBXawChainTop\fP. This will cause -the child to remain a fixed distance from the top and left -edges of the Dialog, and to never resize. -.NH 4 -Special Considerations -.IN "Dialog widget" "special considerations" -.LP -The Dialog widget automatically sets the \fBtop\fP and \fBbottom\fP -resources for all Children that are subclasses of the Command widget, -as well as the widget children that are used to contain the \fBlabel\fP, -\fBvalue\fP, and \fBicon\fP. This policy allows the buttons at the -bottom of the Dialog to interact correctly with the predefined children, -and makes it possible for a client to simply create and manage a new -Command button without having to specify its constraints. -.LP -The Dialog will also set \fBfromLeft\fP to the last button in the -.IN "fromLeft" "" -Dialog for each new button added to the Dialog widget. -.LP -The automatically added constraints cannot be overridden, as they are -policy decisions of the Dialog widget. If a more flexible Dialog is -desired, the application is free to use the Form widget to create its -own Dialog policy. -.NH 3 -Automatically Created Children. -.IN "Dialog widget" "automatically created children" -.LP -The Dialog uses Label widgets to contain the \fBlabel\fP and \fBicon\fP. -These widgets are named \fIlabel\fP and \fIicon\fP respectively. The -Dialog \fBvalue\fP is contained in an AsciiText widget whose name is -\fIvalue\fP. Using \fBXtNameToWidget\fP the application can change -.IN "XtNameToWidget" "" -those resources associated with each of these widgets that are not -available through the Dialog widget itself. -.LP -.NH 3 -Convenience Routines -.LP -To return the character string in the text field, use -.PN XawDialogGetValueString . -.IN "XawDialogGetValueString" "" "@DEF@" -.FD 0 -String XawDialogGetValueString(\fIw\fP) -.br - Widget \fIw\fP; -.FN -.IP \fIw\fP 1i -Specifies the Dialog widget. -.LP -This function returns a copy of the value string of the Dialog -widget. This string is allocated by the AsciiText widget and will -remain valid and unchanged until another call to -\fBXawDialogGetValueString\fP or an \fBXtGetValues\fP call on the -\fBvalue\fP widget, when the string will be automatically freed, and -a new string is returned. This string may be freed earlier by calling -the function \fBXawAsciiSourceFreeString\fP. -.IN "XawAsciiSourceFreeString" "" -.LP -.sp -To add a new button to the Dialog widget use -\fBXawDialogAddButton\fP. -.IN "XawDialogAddButton" "" "@DEF@" -.FD 0 -void XawDialogAddButton(\fIw\fP, \fIname\fP, \fIfunc\fP, \fIclient_data\fP) -.br - Widget \fIw\fP; -.br - String \fIname\fP; -.br - XtCallbackProc \fIfunc\fP; -.br - XtPointer \fIclient_data\fP; -.FN -.IP \fIw\fP 1i -Specifies the Dialog widget. -.IP \fIname\fP 1i -Specifies the name of the new Command button to be added to the Dialog. -.IP \fIfunc\fP 1i -Specifies a callback function to be called when this button is activated. If -NULL is specified then no callback is added. -.IP \fIclient_data\fP 1i -Specifies the client_data to be passed to the \fIfunc\fP. -.LP -This function is merely a shorthand for the code sequence: -.sp -.Ds 0 -.SM -.TA 1i 2i -.ta 1i 2i -{ - Widget button = XtCreateManagedWidget(name, commandWidgetClass, w, NULL, ZERO); - XtAddCallback(button, XtNcallback, func, client_data); -} -.NL -.De -.sp diff --git a/xc/doc/specs/Xaw/Form b/xc/doc/specs/Xaw/Form deleted file mode 100644 index 92e45443a..000000000 --- a/xc/doc/specs/Xaw/Form +++ /dev/null @@ -1,200 +0,0 @@ -.\" $XConsortium: Form,v 1.14 94/05/01 20:44:58 gildea Exp $ -.NH 2 -Form Widget -.LP -.XS - Form Widget -.XE -.IN "Form widget" "" "@DEF@" -.Ds 0 -.TA 2.0i -.ta 2.0i -.sp -Application Header file <X11/Xaw/Form.h> -.IN "Form.h" "" -Class Header file <X11/Xaw/FormP.h> -.IN "FormP.h" "" -Class formWidgetClass -.IN "formWidgetClass" "" -Class Name Form -.IN "Form widget" "class name" -Superclass Constraint -.sp -.De -.LP -The Form widget can contain an arbitrary number of children or -subwidgets. The Form provides geometry management for its children, -which allows individual control of the position of each child. Any -combination of children can be added to a Form. The initial positions -of the children may be computed relative to the positions of previously -created children. When the Form is resized, it computes new positions and -sizes for its children. This computation is based upon information -provided when a child is added to the Form. -.LP -The default width of the Form is the minimum width needed to -enclose the children after computing their initial layout, with a -margin of \fBdefaultDistance\fP -at the right and bottom edges. If a width and height is assigned -to the Form that is too small for the layout, the children will -be clipped by the right and bottom edges of the Form. -.NH 3 -Resources -.LP -When creating an Form widget instance, the following resources are -retrieved from the argument list or from the resource database: -.LP -.IN "Form 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 -defaultDistance Thickness int 4 -depth Depth int C Parent's Depth -destroyCallback Callback XtCallbackList NULL -height Height Dimension A Enough space to contain all children -mappedWhenManaged MappedWhenManaged Boolean True -numChildren ReadOnly Cardinal R 0 -screen Screen Screen R Parent's Screen -sensitive Sensitive Boolean True -translations Translations TranslationTable NULL -width Width Dimension A Enough space to contain all children -x Position Position 0 -y Position Position 0 -.sp 3p -_ -.TE -.Ac -.As -.Bg -.Gp -.Bc -.Bp -.Bw -.Ch -.Cm -.Dd Bold -.Dp -.Dc -.Hw -.Mm -.Nc -.Sc -.Se -.Tr -.Xy -.NH 3 -Constraint Resources -.LP -.IN "Form widget" "constraint resources" -Each child of the Form widget may request special layout resources -be applied to it. These \fIconstraint\fP resources allow the Form -widget's children to specify individual layout requirements. -.LP -.LP -.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 -bottom Edge XawEdgeType XawRubber -fromHoriz Widget Widget NULL (left edge of Form) -fromVert Widget Widget NULL (top edge of Form) -horizDistance Thickness int \fBdefaultDistance\fP resource -left Edge XawEdgeType XawRubber -.IN "XawEdgeType" "" -resizable Boolean Boolean FALSE -right Edge XawEdgeType XawRubber -.IN "XawRubber" "" -top Edge XawEdgeType XawRubber -vertDistance Thickness int \fBdefaultDistance\fP resource -.sp 3p -_ -.TE -.Bt Bold -.Fh Bold -.Hd Bold -.Rl Bold -.NH 3 -Layout Semantics -.LP -.Lt Form -.LP -.TS H -lw(1.5i) lw(1i) lw(3i). -_ -.sp 3p -.TB -Edge Type Resource Name Description -.sp 3p -_ -.TH -.R -.sp 3p -XawChainBottom ChainBottom Edge remains a fixed distance from bottom of Form -.IN "XawChainBottom" "" -XawChainLeft ChainLeft Edge remains a fixed distance from left of Form -.IN "XawChainLeft" "" -XawChainRight ChainRight Edge remains a fixed distance from right of Form -.IN "XawChainRight" "" -XawChainTop ChainTop Edge remains a fixed distance from top of Form -.IN "XawChainTop" "" -XawRubber Rubber Edges will move a proportional distance -.IN "XawRubber" "" -.sp 3p -_ -.TE -.NH 4 -Example -.LP -If you wish to force the Form to never resize one or more of its -children, then set \fBleft\fP and \fBright\fP to \fBXawChainLeft\fP and -\fBtop\fP and \fBbottom\fP to \fBXawChainTop\fP. This will cause the -child to remain a fixed distance from the top and left edges of the -Form, and never to resize. -.NH 3 -Convenience Routines -.LP -To force or defer a re-layout of the Form, use -.PN XawFormDoLayout . -.IN "Form widget" "re-layout" -.IN "XawFormDoLayout" "" "@DEF@" -.FD 0 -void XawFormDoLayout(\fIw\fP, \fIdo_layout\fP) -.br - Widget \fIw\fP; -.br - Boolean \fIdo_layout\fP; -.FN -.IP \fIw\fP 1i -Specifies the Form widget. -.IP \fIdo_layout\fP 1i -Specifies whether the layout of the Form widget is enabled (\fBTrue\fP) -or disabled (\fBFalse\fP). -.LP -When making several changes to the children of a Form widget -after the Form has been realized, it is a good idea to disable -relayout until after all changes have been made. - diff --git a/xc/doc/specs/Xaw/Grip b/xc/doc/specs/Xaw/Grip deleted file mode 100644 index 82d3ff733..000000000 --- a/xc/doc/specs/Xaw/Grip +++ /dev/null @@ -1,157 +0,0 @@ -.\" $XConsortium: Grip,v 1.21 94/05/01 19:21:04 gildea Exp $ -.NH 2 -Grip Widget -.XS - Grip Widget -.XE -.IN "Grip widget" "" "@DEF@" -.Ds 0 -.TA 2.0i -.ta 2.0i -.sp -Application header file <X11/Xaw/Grip.h> -.IN "Grip.h" "" -Class header file <X11/Xaw/GripP.h> -.IN "GripP.h" "" -Class gripWidgetClass -.IN "gripWidgetClass" "" -Class Name Grip -.IN "Grip widget" "class name" -Superclass Simple -.sp -.De -.LP -The Grip widget provides a small rectangular region in which user input -events (such as ButtonPress or ButtonRelease) may be handled. The most -common use for the Grip widget is as an attachment point for visually -repositioning an object, such as the pane border in a Paned widget. -.NH 3 -Resources -.LP -When creating a Grip widget instance, the following resources are -retrieved from the argument list or from the resource database: -.LP -.IN "Grip 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 0 -callback Callback Callback NULL -colormap Colormap Colormap Parent's Colormap -cursor Cursor Cursor None -cursorName Cursor String NULL -depth Depth int C Parent's Depth -destroyCallback Callback XtCallbackList NULL -foreground Foreground Pixel XtDefaultForeground -height Height Dimension 8 -insensitiveBorder Insensitive Pixmap GreyPixmap -international International Boolean C False -mappedWhenManaged MappedWhenManaged Boolean True -pointerColor Foreground Pixel XtDefaultForeground -pointerColorBackground Background Pixel XtDefaultBackground -screen Screen Screen R Parent's Screen -sensitive Sensitive Boolean True -translations Translations TranslationTable NULL -width Width Dimension 8 -x Position Position 0 -y Position Position 0 -.sp 3p -_ -.TE -.Ac -.As -.Bg -.Gp -.Bc -.Bp -.Bw -.IP \fBcallback\fP 1.5i -All routines on this list are called whenever the \fBGripAction\fP -action routine is invoked. The \fIcall_data\fP contains all -information passed to the action routine. A detailed description -is given below in the \fBGrip Actions\fP section. -.Cm -.Cu -.Cn -.Dp -.Dc -.IP \fBforeground\fP 1.5i -A pixel value which indexes the widget's colormap to derive the color -used to flood fill the entire Grip widget. -.Hw -.Ib -.Ix -.Mm -.Pf -.Pb -.Sc -.Se -.Tr -.Xy -.NH 3 -Grip Actions -.IN "Grip widget" "actions" -.LP -The Grip widget does not declare any default event translation bindings, -but it does declare a single action routine named \fBGripAction\fP. The -.IN "Grip widget" "GripAction routine" -client specifies an arbitrary event translation table, optionally giving -parameters to the \fBGripAction\fP routine. -.LP -The \fBGripAction\fP routine executes the callbacks on the -\fBcallback\fP list, passing as \fIcall_data\fP a pointer to a -\fBXawGripCallData\fP structure, defined in the Grip widget's application -header file. -.LP -.Ds 0 -.TA .5i 2.25i -.ta .5i 2.25i -.IN "XawGripCallData" "" "@DEF@" -.IN "XawGripCallDataRec" "" "@DEF@" -.sp -typedef struct _XawGripCallData { - XEvent *event; - String *params; - Cardinal num_params; -} XawGripCallDataRec, *XawGripCallData, - GripCallDataRec, *GripCallData; /* supported for R4 compatibility */ -.IN "XawGripCallDataRec" "" -.IN "XawGripCallData" "" -.IN "GripCallData" "" -.sp -.De -.LP -In this structure, the \fIevent\fP is a pointer to the input event that -triggered the action. \fIparams\fP and \fInum_params\fP give the string -parameters specified in the translation table for the particular event -binding. -.IN "Grip widget" "GripAction table" -.LP -The following is an example of a translation table that uses the GripAction: -.LP -.Ds 0 -.TA .5i 2.5i -.ta .5i 2.5i -.sp - <Btn1Down>: GripAction(press) - <Btn1Motion>: GripAction(move) - <Btn1Up>: GripAction(release) -.sp -.De -For a complete description of the format of translation tables, see the -\fI\*(xT\fP. diff --git a/xc/doc/specs/Xaw/Imakefile b/xc/doc/specs/Xaw/Imakefile deleted file mode 100644 index b1ef8e3a9..000000000 --- a/xc/doc/specs/Xaw/Imakefile +++ /dev/null @@ -1,25 +0,0 @@ -XCOMM $XConsortium: Imakefile,v 1.8 94/05/01 20:39:20 gildea Exp $ -EVERYWHERE=strings.mit strings.xaw -CHAPTER1=CH1 -CHAPTER2=CH2 -CHAPTER3=CH3.intro Command Grip Label List Panner Repeater \ - Scrollbar Simple StripChart Toggle -CHAPTER4=CH4.intro SimpleMenu SmeBSB SmeLine Sme MenuButton -CHAPTER5=CH5.intro TextActions TextFuncs AsciiText AsciiSource AsciiSink \ - TextCustom Text TextSource TextSink -CHAPTER6=CH6.intro Box Dialog Form Paned Porthole Tree Viewport -CHAPTER7=CH7.intro Template - -SRCS = \ - $(EVERYWHERE) TPage_Credits \ - $(CHAPTER1) $(CHAPTER2) $(CHAPTER3) $(CHAPTER4) \ - $(CHAPTER5) $(CHAPTER6) $(CHAPTER7) - -MakeTblDoc(widgets,$(SRCS)) - -MakeDocIndex(widg,widg.idxmac.t) - -XCOMM Useful for running off part of the manual by hand, -XCOMM e.g., make part PART=Label -part: $(PART) - $(TBL) $(PART) | $(TROFF) $(MSMACROS) $(XDOCMACROS) $(EVERYWHERE) - > part.PS diff --git a/xc/doc/specs/Xaw/Label b/xc/doc/specs/Xaw/Label deleted file mode 100644 index f498c159d..000000000 --- a/xc/doc/specs/Xaw/Label +++ /dev/null @@ -1,122 +0,0 @@ -.\" $XConsortium: Label,v 1.20 94/05/01 19:21:10 gildea Exp $ -.NH 2 -Label Widget -.XS - Label Widget -.XE -.IN "Label widget" "" "@DEF@" -.Ds 0 -.TA 2.0i -.ta 2.0i -.sp -Application header file <X11/Xaw/Label.h> -.IN "Label.h" "" -Class header file <X11/Xaw/LabelP.h> -.IN "LabelP.h" "" -Class labelWidgetClass -.IN "labelWidgetClass" "" -Class Name Label -.IN "Label widget" "class name" -Superclass Simple -.sp -.De -.LP -A Label widget holds a graphic displayed within a -rectangular region of the screen. The graphic may be a -text string containing multiple lines of characters in an -8 bit or 16 bit character set (to be displayed with a -\fIfont\fP), or in a multi-byte encoding (for use with a -\fIfontset\fP). The graphic may also be a bitmap or -pixmap. The Label widget will allow its graphic to be -left, right, or center justified. Normally, this widget -can be neither selected nor directly edited by the user. -It is intended for use as an output device only. -.NH 3 -Resources -.LP -When creating a Label widget instance, the following resources are -retrieved from the argument list or from the resource database: -.LP -.IN "Label 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 -bitmap Bitmap Pixmap None -borderColor BorderColor Pixel XtDefaultForeground -borderPixmap Pixmap Pixmap XtUnspecifiedPixmap -borderWidth BorderWidth Dimension 1 -colormap Colormap Colormap Parent's Colormap -cursor Cursor Cursor None -cursorName Cursor String NULL -depth Depth int C Parent's Depth -destroyCallback Callback XtCallbackList NULL -encoding Encoding UnsignedChar XawTextEncoding8bit -font Font XFontStruct XtDefaultFont -fontSet FontSet XFontSet XtDefaultFontSet -foreground Foreground Pixel XtDefaultForeground -height Height Dimension A graphic height + 2 * \fBinternalHeight\fP -insensitiveBorder Insensitive Pixmap GreyPixmap -internalHeight Height Dimension 2 -internalWidth Width Dimension 4 -international International Boolean C False -justify Justify Justify XtJustifyCenter (center) -label Label String name of widget -leftBitmap LeftBitmap Bitmap None -mappedWhenManaged MappedWhenManaged Boolean True -pointerColor Foreground Pixel XtDefaultForeground -pointerColorBackground Background Pixel XtDefaultBackground -resize Resize Boolean True -screen Screen Screen R Parent's Screen -sensitive Sensitive Boolean True -translations Translations TranslationTable See above -width Width Dimension A graphic width + 2 * \fBinternalWidth\fP -x Position Position 0 -y Position Position 0 -.sp 3p -_ -.TE -.Ac -.As -.Bg -.Gp -.Bm Bold -.Bc -.Bp -.Bw -.Cm -.Cu -.Cn -.Dp -.Dc -.Le Bold -.Lf Bold -.Ls Bold -.Lg Bold -.Hw -.Ib -.Ih Bold -.In -.Ju Bold -.La Bold -.Ll Bold -.Mm -.Pf -.Pb -.Re Bold -.Sc -.Se -.Tr -.Xy diff --git a/xc/doc/specs/Xaw/List b/xc/doc/specs/Xaw/List deleted file mode 100644 index a706553b8..000000000 --- a/xc/doc/specs/Xaw/List +++ /dev/null @@ -1,341 +0,0 @@ -.\" $XConsortium: List,v 1.23 94/05/01 19:21:04 gildea Exp $ -.NH 2 -List Widget -.LP -.XS - List Widget -.XE -.IN "List widget" "" "@DEF@" -.Ds 0 -.TA 2.0i -.ta 2.0i -.sp -Application header file <X11/Xaw/List.h> -.IN "List.h" "" -Class header file <X11/Xaw/ListP.h> -.IN "ListP.h" "" -Class listWidgetClass -.IN "listWidgetClass" "" -Class Name List -.IN "List widget" "class name" -Superclass Simple -.sp -.De -.LP - -The List widget contains a list of strings formatted into rows and -columns. When one of the strings is selected, it is highlighted, and the -List widget's \fBNotify\fP action is invoked, calling all routines on -its callback list. Only one string may be selected at a time. -.NH 3 -Resources -.LP -When creating a List widget instance, the following resources are -retrieved from the argument list or from the resource database: -.LP -.IN "List 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 -callback Callback Callback NULL -colormap Colormap Colormap Parent's Colormap -columnSpacing Spacing Dimension 6 -cursor Cursor Cursor XC_left_ptr -cursorName Cursor String NULL -defaultColumns Columns int 2 -depth Depth int C Parent's Depth -destroyCallback Callback XtCallbackList NULL -font Font FontStruct XtDefaultFont -fontSet FontSet XFontSet XtDefaultFontSet -forceColumns Columns Boolean False -foreground Foreground Pixel XtDefaultForeground -height Height Dimension A Enough space to contain the list -insensitiveBorder Insensitive Pixmap GreyPixmap -internalHeight Height Dimension 2 -internalWidth Width Dimension 4 -international International Boolean C False -list List Pointer name of widget -longest Longest int A 0 -mappedWhenManaged MappedWhenManaged Boolean True -numberStrings NumberStrings int A computed for NULL terminated list -pasteBuffer Boolean Boolean False -pointerColor Foreground Pixel XtDefaultForeground -pointerColorBackground Background Pixel XtDefaultBackground -rowSpacing Spacing Dimension 2 -screen Screen Screen R Parent's Screen -sensitive Sensitive Boolean True -translations Translations TranslationTable See below -verticalList Boolean Boolean False -width Width Dimension A Enough space to contain the list -x Position Position 0 -y Position Position 0 -.sp 3p -_ -.TE -.Ac -.As -.Bg -.Gp -.Bc -.Bp -.Bw -.IP \fBcallback\fP 1.5i -All functions on this list are called whenever the \fBnotify\fP action is -invoked. The \fIcall_data\fP argument contains information about the element -selected and is described in detail in the \fBList Callbacks\fP section. -.Cm -.IP \fBcolumnSpacing\fP 1.5i -.br -.ns -.IP \fBrowSpacing\fP 1.5i -The amount of space, in pixels, between each of the rows and columns -in the list. -.Cu -.Cn -.IP \fBdefaultColumns\fP 1.5i -The default number of columns. This value is used when neither the -width nor the height of the List widget is specified or when -\fBforceColumns\fP is \fBTrue\fP. -.Dp -.Dc -.IP \fBfont\fP -The text font to use when displaying the \fBlist\fP, when the -\fBinternational\fP resource is \fBfalse\fP. -.IP \fBfontSet\fP -The text font set to use when displaying the \fBlist\fP, when the -\fBinternational\fP resource is \fBtrue\fP. -.IP \fBforceColumns\fP -Forces the default number of columns to be used regardless of the -List widget's current size. -.IP \fBforeground\fP 1.5i -A pixel value which indexes the widget's colormap to derive the color -used to paint the text of the list elements. -.Hw -.Ib -.IP \fPinternalHeight\fP 1.5i -.br -.ns -.IP \fPinternalWidth\fP 1.5i -The margin, in pixels, between the edges of the list and the -corresponding edge of the List widget's window. -.IP \fBlist\fP 1.5i -An array of text strings displayed in the List widget. If -\fBnumberStrings\fP is zero (the default) then the \fBlist\fP must be -NULL terminated. If a value is not specified for the \fBlist\fP, then -\fBnumberStrings\fP is set to 1, and the name of the widget is used as -the \fBlist\fP, and \fBlongest\fP is set to the length of the name of the -widget. The \fBlist\fP is used in place, and must be available -to the List widget for the lifetime of this widget, or until it is -changed with \fBXtSetValues\fP or \fBXawListChange\fP. -.In -.IP \fBlongest\fP -Specifies the width, in pixels, of the longest string in the current -list. The List widget will compute this value if zero (the default) -is specified. If this resource is set by hand, entries longer than this -will be clipped to fit. -.Mm -.IP \fBnumberStrings\fP 1.5i -The number of strings in the current list. If a value of zero (the -default) is specified, the List widget will compute it. When computing -the number of strings the List widget assumes that the \fBlist\fP is NULL -terminated. -.IP \fBpasteBuffer\fP 1.5i -If this resource is set to \fBTrue\fP then the name of the currently -selected list element will be put into \fBCUT_BUFFER_0\fP. -.Pf -.Pb -.Sc -.Se -.Tr -.IP \fBverticalList\fP 1.5i -If this resource is set to \fBTrue\fP then the list elements will be -presented in column major order. -.Xy -.NH 3 -List Actions -.IN "List widget" "actions" -.LP -The List widget supports the following actions: -.IP \(bu 5 -Highlighting and unhighlighting the list element under the -pointer with \fBSet\fP and \fBUnset\fP -.IP \(bu 5 -Processing application callbacks with \fBNotify\fP -.LP -The following is the default translation table used by the List Widget: -.IN "List widget" "default translation table" -.LP -.Ds -.TA .5i 2.25i -.ta .5i 2.25i -<Btn1Down>,<Btn1Up>: Set(\|) Notify(\|) -.sp -.De -.LP -The full list of actions supported by List widget is: -.IP \fBSet\fP(\|) 1.5i -\fISets\fP the list element that is currently under the pointer. To -inform the user that this element is currently set, it is drawn with -foreground and background colors reversed. If this action is called when -there is no list element under the cursor, the currently \fIset\fP -element will be \fIunset\fP. -.IP \fBUnset\fP(\|) 1.5i -Cancels the \fIset\fP state of the element under the pointer, -and redraws it with normal foreground and background colors. -.IP \fBNotify\fP(\|) 1.5i -Calls all callbacks on the List widget's callback list. Information -about the currently selected list element is passed in the -\fIcall_data\fP argument (see \fBList Callbacks\fP below). -.NH 3 -List Callbacks -.IN "List widget" "callbacks" -.LP -All procedures on the List widget's callback list will have a -\fBXawListReturnStruct\fP passed to them as \fIcall_data\fP. The -structure is defined in the List widget's application header file. -.LP -.Ds 0 -.TA .5i 2.25i -.ta .5i 2.25i -.IN "XawListReturnStruct" "" "@DEF@" -typedef struct _XawListReturnStruct { - String string; /* string shown in the list. */ - int list_index; /* index of the item selected. */ -} XawListReturnStruct; -.IN "XawListReturnStruct" "" -.NT -The \fIlist_index\fP item used to be called simply \fIindex\fP. -Unfortunately, this name collided with a global name defined on some -operating systems, and had to be changed. -.NE -.De -.NH 3 -Changing the List -.LP -To change the list that is displayed, use -.PN XawListChange . -.IN "XawListChange" "" "@DEF@" -.FD 0 -void XawListChange(\fIw\fP, \fIlist\fP, \fInitems\fP, \fIlongest\fP, \fIresize\fP) -.br - Widget \fIw\fP; -.br - String * \fIlist\fP; -.br - int \fInitems\fP, \fIlongest\fP; -.br - Boolean \fIresize\fP; -.FN -.IP \fIw\fP 1i -Specifies the List widget. -.IP \fIlist\fP 1i -Specifies the new list for the List widget to display. -.IP \fInitems\fP 1i -Specifies the number of items in the \fIlist\fP. If a value less than 1 -is specified, \fIlist\fP must be NULL terminated, and the number of -items will be calculated by the List widget. -.IP \fIlongest\fP 1i -Specifies the length of the longest item in the \fIlist\fP in pixels. -If a value less than 1 is specified, the List widget will calculate the -value. -.IP \fIresize\fP 1i -Specifies a Boolean value that if \fBTrue\fP indicates that the -List widget should try to resize itself after making the change. -The constraints of the List widget's parent are always enforced, -regardless of the value specified here. -.LP -.PN XawListChange -will \fIunset\fP all list elements that are currently \fBset\fP before -the list is actually changed. The \fIlist\fP is used in place, and must -remain usable for the lifetime of the List widget, or until \fIlist\fP -has been changed again with this function or with \fBXtSetValues\fP. -.NH 3 -Highlighting an Item -.LP -To highlight an item in the list, use -.PN XawListHighlight . -.IN "XawListHighlight" "" "@DEF@" -.FD 0 -void XawListHighlight(\fIw\fP, \fIitem\fP) -.br - Widget \fIw\fP; -.br - int \fIitem\fP; -.FN -.IP \fIw\fP 1i -Specifies the List widget. -.IP \fIitem\fP 1i -Specifies an index into the current list that indicates the item to be -highlighted. -.LP -Only one item can be highlighted at a time. -If an item is already highlighted when -.PN XawListHighlight -is called, -the highlighted item is unhighlighted before the new item is highlighted. -.NH 3 -Unhighlighting an Item -.LP -To unhighlight the currently highlighted item in the list, use -.PN XawListUnhighlight . -.IN "XawListUnhighlight" "" "@DEF@" -.FD 0 -void XawListUnhighlight(\fIw\fP) -.br - Widget \fIw\fP; -.FN -.IP \fIw\fP 1i -Specifies the List widget. -.NH 3 -Retrieving the Currently Selected Item -.LP -To retrieve the list element that is currently \fIset\fP, use -.PN XawListShowCurrent . -.IN "XawListShowCurrent" "" "@DEF@" -.FD 0 -XawListReturnStruct *XawListShowCurrent(\fIw\fP) -.br - Widget \fIw\fP; -.FN -.IP \fIw\fP 1i -Specifies the List widget. -.LP -.PN XawListShowCurrent -returns a pointer to an -.PN XawListReturnStruct -structure, -containing the currently highlighted item. -If the value of the index member is XAW_LIST_NONE, -.IN "XAW_LIST_NONE" -the string member is undefined, and no item is currently selected. -.NH 3 -Restrictions -.LP -Many programmers create a ``scrolled list'' by putting a List -widget with many entries as a child of a Viewport widget. The -List continues to create a window as big as its contents, but -that big window is only visible where it intersects the parent -Viewport's window. (I.e., it is ``clipped.'') -.LP -While this is a useful technique, there is a serious drawback. -X does not support windows above 32,767 pixels in width or -height, but this height limit will be exceeded by a List's -window when the List has many entries (i.e., with a 12 point -font, about 3000 entries would be too many.) -.LP diff --git a/xc/doc/specs/Xaw/MenuButton b/xc/doc/specs/Xaw/MenuButton deleted file mode 100644 index 14321344e..000000000 --- a/xc/doc/specs/Xaw/MenuButton +++ /dev/null @@ -1,215 +0,0 @@ -.\" $XConsortium: MenuButton,v 1.21 94/05/02 08:21:49 gildea Exp $ -.NH 2 -MenuButton Widget -.XS - MenuButton Widget -.XE -.IN "MenuButton widget" "" "@DEF@" -.sp -.Ds 0 -.TA 2.0i -.ta 2.0i -Application Header file <X11/Xaw/MenuButton.h> -.IN "MenuButton.h" "" -Class Header file <X11/Xaw/MenuButtonP.h> -.IN "MenuButtonP.h" "" -Class menuButtonWidgetClass -.IN "menuButtonWidgetClass" "" -Class Name MenuButton -.IN "MenuButton widget" "class name" -Superclass Command -.De -.LP -.sp -The MenuButton widget is an area, often rectangular, -that displays a graphic. The graphic may be a text -string containing multiple lines of characters in an 8 -bit or 16 bit character set (to be displayed with a -\fIfont\fP), or in a multi-byte encoding (for use with -a \fIfontset\fP). The graphic may also be a bitmap or -pixmap. -.LP -When the pointer cursor is on a MenuButton widget, the -MenuButton becomes highlighted by drawing a rectangle -around its perimeter. This highlighting indicates -that the MenuButton is ready for selection. When a -pointer button is pressed, the MenuButton widget will -pop up the menu named in the \fBmenuName\fP resource. -.NH 3 -Resources -.LP -When creating a MenuButton widget instance, -the following resources are retrieved from the argument list -or from the resource database: -.LP -.IN "MenuButton 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 -bitmap Bitmap Pixmap None -borderColor BorderColor Pixel XtDefaultForeground -borderPixmap Pixmap Pixmap XtUnspecifiedPixmap -borderWidth BorderWidth Dimension 1 -callback Callback XtCallbackList NULL -colormap Colormap Colormap Parent's Colormap -cornerRoundPercent CornerRoundPercent Dimension 25 -cursor Cursor Cursor None -cursorName Cursor String None -depth Depth int C Parent's Depth -destroyCallback Callback XtCallbackList NULL -encoding Encoding UnsignedChar XawTextEncoding8bit -font Font XFontStruct XtDefaultFont -fontSet FontSet XFontSet XtDefaultFontSet -foreground Foreground Pixel XtDefaultForeground -height Height Dimension A graphic height + 2 * \fBinternalHeight\fP -highlightThickness Thickness Dimension A 2 (0 if Shaped) -insensitiveBorder Insensitive Pixmap GreyPixmap -internalHeight Height Dimension 2 -internalWidth Width Dimension 4 -international International Boolean C False -justify Justify Justify XtJustifyCenter (center) -label Label String name of widget -leftBitmap LeftBitmap Bitmap None -mappedWhenManaged MappedWhenManaged Boolean True -menuName MenuName String "menu" -pointerColor Foreground Pixel XtDefaultForeground -pointerColorBackground Background Pixel XtDefaultBackground -resize Resize Boolean True -screen Screen Screen R Parent's Screen -sensitive Sensitive Boolean True -shapeStype ShapeStyle ShapeStyle Rectangle -translations Translations TranslationTable See below -width Width Dimension A graphic width + 2 * \fBinternalWidth\fP -x Position Position 0 -y Position Position 0 -.sp 3p -_ -.TE -.Ac -.As -.Bg -.Gp -.Bm -.Bc -.Bp -.Bw -.Cb -.Cm -.Cr -.Cu -.Cn -.Dp -.Dc -.Lf -.Ls -.Lg -.Hw -.Ht -.Ib -.Ih -.In -.Ju -.La -.Mm -.IP \fBmenuName\fP 1.5i -The name of a popup shell to popup as a menu. The MenuButton -will search for this name using \fBXtNameToWidget\fP starting -with itself as the reference widget. If the search is -unsuccessful the widget will continue up the widget tree using -each of its ancestors as the reference widget passed to -\fBXtNameToWidget\fP. If no widget of called \fBmenuName\fP is -found by this algorithm, the widget will print a warning message -and give up. When the menu is found it will be popped up -exclusive and spring_loaded. The MenuButton widget does not -copy the value of this resource into newly allocated memory. The -application programmer must pass the resource value in -nonvolatile memory. -.Pf -.Pb -.Re -.Sc -.Se -.Ss -.Tr -.Xy -.NH 3 -MenuButton Actions -.IN "MenuButton widget" "actions" -.LP -The MenuButton widget supports the following actions: -.IP \(bu 5 -Switching the button between the foreground and background -colors with \fBset\fP and \fBunset\fP -.IP \(bu 5 -Processing application callbacks with \fBnotify\fP -.IP \(bu 5 -Switching the internal border between highlighted -and unhighlighted states with \fBhighlight\fP and \fBunhighlight\fP -.IP \(bu 5 -Popping up a menu with \fBPopupMenu\fP -.LP -The following are the default translation bindings used by the -MenuButton widget: -.LP -.sp -.Ds 0 -.TA .5i 2.25i -.ta .5i 2.25i - <EnterWindow>: highlight(\|) - <LeaveWindow>: reset(\|) - <BtnDown>: reset(\|) PopupMenu(\) -.De -.NH 3 -MenuButton Actions -.LP -The full list of actions supported by MenuButton is: -.IP \fBhighlight\fP(\fIcondition\fP) 1.5i -Displays the internal highlight border in the color (\fBforeground\fP -or \fBbackground\fP ) that contrasts with the interior color of the -Command widget. The conditions \fBWhenUnset\fP and \fBAlways\fP are -understood by this action procedure. If no argument is passed, -\fBWhenUnset\fP is assumed. -.IP \fBunhighlight\fP(\|) 1.5i -Displays the internal highlight border in the color (\fBXtNforeground\fP -or \fBbackground\fP ) that matches the interior color of the -MenuButton widget. -.IP \fBset\fP(\|) 1.5i -Enters the \fIset\fP state, in which \fBnotify\fP is possible. This -action causes the button to display its interior in the -\fBforeground\fP color. The label or bitmap is displayed in the -\fBbackground\fP color. -.IP \fBunset\fP(\|) 1.5i -Cancels the \fIset\fP state and displays the interior of the button in the -\fBbackground\fP color. The label or bitmap is displayed in the -\fBforeground\fP color. -.IP \fBreset\fP(\|) 1.5i -Cancels any \fBset\fP or \fBhighlight\fP and displays the interior of the -button in the \fBbackground\fP color, with the label displayed in the -\fBforeground\fP color. -.IP \fBnotify\fP(\|) 1.5i -When the button is in the \fBset\fP state this action calls all functions in -the callback list named by the \fBcallback\fP resource. The value of -the call_data argument in these callback functions is undefined. -.IP \fBPopupMenu\fP(\|) 1.5i -Pops up the menu specified by the \fBmenuName\fP resource. -.LP -The MenuButton widget does not place a server grab on itself. -Instead, PopupMenu is registered as a grab action. -As a result, clients which popup menus without using XtMenuPopup -or MenuPopup or PopupMenu in translations will fail to have a grab active. -They should make a call to XtRegisterGrabAction on the appropriate action -in the application initialization routine, or use a different translation. -.bp diff --git a/xc/doc/specs/Xaw/Paned b/xc/doc/specs/Xaw/Paned deleted file mode 100644 index 2a44f6fae..000000000 --- a/xc/doc/specs/Xaw/Paned +++ /dev/null @@ -1,492 +0,0 @@ -.\" $XConsortium: Paned,v 1.21 94/05/01 20:44:58 gildea Exp $ -.NH 2 -Paned Widget -.LP -.XS - Paned Widget -.XE -.IN "Paned widget" "" "@DEF@" -.Ds 0 -.TA 2.0i -.ta 2.0i -.sp -Application Header file <X11/Xaw/Paned.h> -.IN "Paned.h" "" -Class Header file <X11/Xaw/PanedP.h> -.IN "PanedP.h" "" -Class panedWidgetClass -.IN "panedWidgetClass" "" -Class Name Paned -.IN "Paned widget" "class name" -Superclass Constraint -.sp -.De -.LP -The Paned widget manages children in a vertically or horizontally -tiled fashion. The panes may be dynamically resized by the user by -using the \fIgrips\fP that appear near the right or bottom edge of the -border between two panes. -.LP -The Paned widget may accept any widget class as a pane \fBexcept\fP -Grip. Grip widgets have a special meaning for the Paned widget, and -adding a Grip as its own pane will confuse the Paned widget. -.NH 3 -Using the Paned Widget -.IN "Paned widget" "using" -.LP -The grips allow the panes to be resized by the user. The semantics of -how these panes resize is somewhat complicated, and warrants further -explanation here. When the mouse pointer is positioned on a grip and -pressed, an arrow is displayed that indicates the pane that is to be to -be resized. While keeping the mouse button down, the user can move the -grip up and down (or left and right). This, in turn, changes the size -of the pane. The size of the Paned widget will not change. Instead, -it chooses another pane (or panes) to resize. For more details on which -pane it chooses to resize, see \fBLayout Semantics\fP. -.LP -One pointer binding allows the border between two panes to be moved, -without affecting any of the other panes. When this occurs the pointer -will change to an arrow that points along the pane border. -.LP -The default bindings for the Paned widget's grips are: -.TS H -lw(1i) lw(2i) lw(2i). -_ -.sp 3p -.TB -Mouse button Pane to Resize - Vertical Pane to Resize - Horizontal -.sp 3p -_ -.TH -.R -.sp 3p -1 (left) above the grip left of the grip -2 (middle) adjust border adjust border -3 (right) below the grip right of the grip -.sp 3p -_ -.TE -.NH 3 -Resources -.LP -When creating a Paned widget instance, the following resources are -retrieved from the argument list or the resource database: -.LP -.IN "Paned widget" "resources" -.TS H -expand; -lw(1i) lw(1i) lw(1i) lw(.4i) 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 -betweenCursor Cursor Cursor A Depends on orientation -borderColor BorderColor Pixel XtDefaultForeground -borderPixmap Pixmap Pixmap XtUnspecifiedPixmap -borderWidth BorderWidth Dimension 1 -children ReadOnly WidgetList R NULL -colormap Colormap Colormap Parent's Colormap -cursor Cursor Cursor None -depth Depth int C Parent's Depth -destroyCallback Callback XtCallbackList NULL -gripCursor Cursor Cursor A Depends on orientation -gripIndent GripIndent Position 10 -gripTranslations Translations TranslationTable see below -height Height Dimension A Depends on orientation -horizontalBetweenCursor Cursor Cursor sb_up_arrow -horizontalGripCursor Cursor Cursor sb_h_double_arrow -internalBorderColor BorderColor Pixel XtDefaultForeground -internalBorderWidth BorderWidth Dimension 1 -leftCursor Cursor Cursor sb_left_arrow -lowerCursor Cursor Cursor sb_down_arrow -mappedWhenManaged MappedWhenManaged Boolean True -numChildren ReadOnly Cardinal R 0 -orientation Orientation Orientation XtorientVertical -refigureMode Boolean Boolean True -rightCursor Cursor Cursor sb_right_arrow -screen Screen Screen R Parent's Screen -sensitive Sensitive Boolean True -translations Translations TranslationTable NULL -upperCursor Cursor Cursor sb_up_arrow -verticalBetweenCursor Cursor Cursor sb_left_arrow -verticalGripCursor Cursor Cursor sb_v_double_arrow -width Width Dimension A Depends on orientation -x Paned Position 0 -y Paned Position 0 -.sp 3p -_ -.TE -.Ac -.As -.Bg -.Gp -.Bc -.Bp -.Bw -.Ch -.Cm -.IP \fBcursor\fP 1.5i -The cursor to use when the mouse pointer is over the Paned widget, but -not in any of its children (children may also inherit this cursor). It -should be noted that the internal borders are actually part of the Paned -widget, not the children. -.Dp -.Dc -.IP \fBgripCursor\fP 1.5i -The cursor to use when the grips are not active. The default value is -\fBverticalGripCursor\fP or \fBhorizontalGripCursor\fP depending on -the orientation of the Paned widget. -.IP \fBgripIndent\fP 1.5i -The amount of space left between the right (or bottom) edge of the -Paned widget and all the grips. -.IP \fBgripTranslation\fP 1.5i -Translation table that will be applied to all grips. -.Hw -.IP \fBhorizontalBetweenCursor\fP 1.5i -.br -.ns -.IP \fBverticalBetweenCursor\fP 1.5i -The cursor to be used for the grip when changing the boundary between -two panes. These resources allow the cursors to be different -depending on the orientation of the Paned widget. -.IP \fBhorizontalGripCursor\fP 1.5i -.br -.ns -.IP \fBverticalGripCursor\fP 1.5i -The cursor to be used for the grips when they are not active. These -resources allow the cursors to be different depending on the -orientation of the Paned widget. -.IP \fBinternalBorderColor\fP 1.5i -A pixel value which indexes the widget's colormap to derive the internal -border color of the widget's window. The class name of this resource -allows \fIPaned*BorderColor: blue\fP to set the internal border color -for the Paned widget. An optimization is invoked if -\fBinternalBorderColor\fP and \fBbackground\fP are the same, and the -internal borders are not drawn. \fBinternalBorderWidth\fP is still left -between the panes, however. -.IP \fBinternalBorderWidth\fP 1.5i -The width of the internal borders. This is the amount of space left -between the panes. The class name of this resource allows -\fIPaned*BorderWidth: 3\fP to set the internal border width for the -Paned widget. -.IP \fBleftCursor\fP 1.5i -.br -.ns -.IP \fBrightCursor\fP 1.5i -The cursor used to indicate which is the \fIimportant\fP pane to resize -when the Paned widget is oriented horizontally. -.IP \fBlowerCursor\fP 1.5i -.br -.ns -.IP \fBupperCursor\fP 1.5i -The cursor used to indicate which is the \fIimportant\fP pane to resize -when the Paned widget is oriented vertically. -.Mm -.Nc -This is not the same as the number of panes, since this also contains a -grip for some of the panes, use \fBXawPanedGetNumSub\fP to retrieve the -number of panes. -.IP \fBorientation\fP 1.5i -The orientation to stack the panes. This value can be either -\fBXtorientVertical\fP or \fBXtorientHorizontal\fP. -.IN "XtorientVertical" "" -.IN "XtorientHorizontal" "" -.IN "conversions" "Orientation" -.Rs "vertical \fPand\fB horizontal" -.IP \fBrefigureMode\fP 1.5i -This resource allows pane layout to be suspended. If this value is -\fBFalse\fP, then no layout actions will be taken. This may improve -efficiency when adding or removing more than one pane from the Paned -widget. -.Sc -.Se -.Tr -.Xy -.NH 3 -Constraint Resources -.LP -.IN "Paned widget" "constraint resources" -Each child of the Paned widget may request special layout resources -be applied to it. These \fIconstraint\fP resources allow the Paned -widget's children to specify individual layout requirements. -.LP -.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 -allowResize Boolean Boolean False -max Max Dimension Infinity -min Min Dimension Height of Grips -preferredPaneSize PreferredPaneSize Dimension ask child -resizeToPreferred Boolean Boolean False -showGrip ShowGrip Boolean True -skipAdjust Boolean Boolean False -.sp 3p -_ -.TE -.IP \fBallowResize\fP 1.5i -If this value is \fBFalse\fP the the Paned widget will disallow all -geometry requests from this child. -.IP \fBmax\fP 1.5i -.br -.ns -.IP \fBmin\fP 1.5i -The absolute maximum or minimum size for this pane. These values will -never be overridden by the Paned widget. This may cause some panes to be -pushed off the bottom (or right) edge of the paned widget. -.IP \fBpreferredPaneSize\fP 1.5i -Normally the paned widget makes a QueryGeometry call on a child to -determine the preferred size of the child's pane. There are times -when the application programmer or the user has a better idea of the -preferred size of a pane. Setting this resource causes the value -passed to be interpreted as the preferred size, in pixels, of this pane. -.IP \fBresizeToPreferred\fP 1.5i -Determines whether or not to resize each pane to its preferred size -when the Paned widget is resized. See \fBLayout Semantics\fP for details. -.IP \fBshowGrip\fP 1.5i -If \fBTrue\fP then a grip will be shown for this pane. The grip -associated with a pane is either below or to the right of the pane. No -grip is ever shown for the last pane. -.IP \fBskipAdjust\fP 1.5i -This resource is used to determine which pane is forced to be resized. -Setting this value to \fBTrue\fP makes this pane less likely to be -forced to be resized. See \fBLayout Semantics\fP for details. -.NH 3 -Layout Semantics -.LP -.IN "Paned widget" "layout semantics" -In order to make effective use of the Paned widget it is helpful to know -the rules it uses to determine which child will be resized in any given -situation. There are three rules used to determine which child is -resized. While these rules are always the same, the panes that are -searched can change depending upon what caused the relayout. -.LP -.sp -\fBLayout Rules\fP -.IP \fB1\fP .5i -Do not let a pane grow larger than its \fBmax\fP or smaller than its -\fBmin\fP. -.IP \fB2\fP .5i -Do not adjust panes with \fBskipAdjust\fP set. -.IP \fB3\fP .5i -Do not adjust panes away from their preferred size, although moving one -closer to its preferred size is fine. -.LP -When searching the children the Paned widget looks for panes that -satisfy all the rules, and if unsuccessful then it eliminates rule 3 -and then 2. Rule 1 is always enforced. -.LP -If the relayout is due to a resize or change in management then the -panes are searched from bottom to top. If the relayout is due to grip -movement then they are searched from the grip selected in the direction -opposite the pane selected. -.NH 4 -Resizing Panes from a Grip Action -.LP -The pane above the grip is resized by invoking the GripAction with -\fBUpLeftPane\fP specified. The panes below the grip are each checked -against all rules, then rules 2 and 1 and finally against rule 1 only. -No pane above the chosen pane will ever be resized. -.LP -The pane below the grip is resized by invoking the GripAction with -\fBLowRightPane\fP specified. The panes above the grip are each -checked in this case. No pane below the chosen pane will ever be resized. -.LP -Invoking GripAction with \fBThisBorderOnly\fP specified just moves the -border between the panes. No other panes are ever resized. -.NH 4 -Resizing Panes after the Paned widget is resized. -.LP -When the Pane widget is resized it must determine a new size for each -pane. There are two methods of doing this. The Paned widget can either -give each pane its preferred size and then resize the panes to fit, or -it can use the current sizes and then resize the panes to fit. The -\fBresizeToPreferred\fP resource allows the application to tell the -Paned widget whether to query the child about its preferred size -(subject to the the \fBpreferredPaneSize\fP) or to use the current size -when refiguring the pane locations after the pane has been resized. -.LP -There is one special case. All panes assume they should resize to -their preferred size until the Paned widget becomes visible to the user. -.NH 4 -Managing Children and Geometry Management -.LP -The Paned widget always resizes its children to their preferred sizes when -a new child is managed, or a geometry management request is honored. -The Paned widget will first attempt to resize itself to contain its -panes exactly. If this is not possible then it will hunt through the -children, from bottom to top (right to left), for a pane to resize. -.NH 4 -Special Considerations -.LP -When a user resizes a pane with the grips, the Paned widget assumes that -this new size is the preferred size of the pane. -.NH 3 -Grip Translations -.LP -The Paned widget has no action routines of its own, as all actions are -handled through the grips. The grips are each assigned a default -Translation table. -.LP -.sp -.Ds 0 -.TA .5i 2.25i -.ta .5i 2.25i - <Btn1Down>: GripAction(Start, UpLeftPane) -.IN "GripAction" "" - <Btn2Down>: GripAction(Start, ThisBorderOnly) - <Btn3Down>: GripAction(Start, LowRightPane) - <Btn1Motion>: GripAction(Move, UpLeftPane) - <Btn2Motion>: GripAction(Move, ThisBorderOnly) - <Btn3Motion>: GripAction(Move, LowRightPane) - Any<BtnUp>: GripAction(Commit) -.De -.sp -.LP -The Paned widget interprets the \fBGripAction\fP as taking two arguments. -.IN "GripAction" "" -The first argument may be any of the following: -.IP \fBStart\fP 1i -Sets up the Paned widget for resizing and changes the cursor of the -grip. The second argument determines which pane will be resized, and -can take on any of the three values shown above. -.IP \fBMove\fP 1i -The internal borders are drawn over the current pane locations to -animate where the borders would actually be placed if you were to move -this border as shown. The second argument must match the second argument -that was passed to the \fBStart\fP action, that began this process. If -these arguments are not passed, the behavior is undefined. -.IP \fBCommit\fP 1i -This argument causes the Paned widget to commit the changes selected -by the previously started action. The cursor is changed back to the -grip's inactive cursor. No second argument is needed in this case. -.NH 3 -Convenience Routines -.LP -.IN "Paned widget" "enable pane resizing" -.IN "Paned widget" "disable pane resizing" -To enable or disable a child's request for pane resizing, -use -.PN XawPanedAllowResize : -.IN "XawPanedAllowResize" "" "@DEF@" -.FD 0 -void XawPanedAllowResize(\fIw\fP, \fIallow_resize\fP) -.br - Widget \fIw\fP; -.br - Boolean \fIallow_resize\fP; -.FN -.IP \fIw\fP 1i -Specifies the child pane. -.IP \fIallow_resize\fP -Specifies whether or not resizing requests for this child will be -granted by the Paned widget. -.LP -If allow_resize is \fBTrue\fP, the Paned widget allows geometry -requests from the child to change the pane's height. If allow_resize -is \fBFalse\fP, the Paned widget ignores geometry requests from the -child to change the pane's height. The default state is \fBTrue\fP -before the Pane is realized and \fBFalse\fP after it is realized. -This procedure is equivalent to changing the \fBallowResize\fP -constraint resource for the child. -.LP -.sp -.IN "Paned widget" "change height settings" -To change the minimum and maximum height settings for a pane, use -.PN XawPanedSetMinMax : -.IN "XawPanedSetMinMax" "" "@DEF@" -.FD 0 -void XawPanedSetMinMax(\fIw\fP, \fImin\fP, \fImax\fP) -.br - Widget \fIw\fP; -.br - int \fImin\fP, \fImax\fP; -.FN -.IP \fIw\fP 1i -Specifies the child pane. -.IP \fImin\fP 1i -Specifies the new minimum height of the child, expressed in pixels. -.IP \fImax\fP 1i -Specifies new maximum height of the child, expressed in pixels. -.LP -This procedure is equivalent to setting the \fBmin\fP and \fBmax\fP -constraint resources for the child. -.LP -.sp -.IN "Paned widget" "get height settings" -To retrieve the minimum and maximum height settings for a pane, use -.PN XawPanedGetMinMax : -.IN "XawPanedGetMinMax" "" "@DEF@" -.FD 0 -void XawPanedGetMinMax(\fIw\fP, \fImin_return\fP, \fImax_return\fP) -.br - Widget \fIw\fP; -.br - int \fI*min_return\fP, \fI*max_return\fP; -.FN -.IP \fIw\fP 1i -Specifies the child pane. -.IP \fImin_return\fP 1i -Returns the minimum height of the child, expressed in pixels. -.IP \fImax_return\fP 1i -Returns the maximum height of the child, expressed in pixels. -.LP -This procedure is equivalent to getting the \fBmin\fP and \fBmax\fP -resources for this child child. -.LP -.sp -.IN "Paned widget" "enable auto-reconfiguring" -.IN "Paned widget" "disable auto-reconfiguring" -To enable or disable automatic recalculation of pane sizes and positions, -use -.PN XawPanedSetRefigureMode : -.IN "XawPanedSetRefigureMode" "" "@DEF@" -.FD 0 -void XawPanedSetRefigureMode(\fIw\fP, \fImode\fP) -.br - Widget \fIw\fP; -.br - Boolean \fImode\fP; -.FN -.IP \fIw\fP 1i -Specifies the Paned widget. -.IP \fImode\fP 1i -Specifies whether the layout of the Paned widget is enabled (\fBTrue\fP) -or disabled (\fBFalse\fP). -.LP -When making several changes to the children of a Paned widget -after the Paned has been realized, it is a good idea to disable -relayout until after all changes have been made. -.LP -.sp -.IN "Paned widget" "getting the number of children" -To retrieve the number of panes in a paned widget use -\fBXawPanedGetNumSub\fP: -.IN "XawPanedGetNumSub" "" "@DEF@" -.FD 0 -int XawPanedGetNumSub(\fIw\fP) -.br - Widget \fIw\fP; -.FN -.IP \fIw\fP 1i -Specifies the Paned widget. -.LP -This function returns the number of panes in the Paned widget. This is -\fBnot\fP the same as the number of children, since the grips are also -children of the Paned widget. diff --git a/xc/doc/specs/Xaw/Panner b/xc/doc/specs/Xaw/Panner deleted file mode 100644 index 245ee8767..000000000 --- a/xc/doc/specs/Xaw/Panner +++ /dev/null @@ -1,247 +0,0 @@ -.\" $XConsortium: Panner,v 1.8 94/05/01 19:21:19 gildea Exp $ -.NH 2 -Panner Widget -.LP -.XS - Panner Widget -.XE -.IN "Panner widget" "" "@DEF@" -.Ds 0 -.TA 2.0i -.ta 2.0i -.sp -Application header file <X11/Xaw/Panner.h> -.IN "Panner.h" "" -Class header file <X11/Xaw/PannerP.h> -.IN "PannerP.h" "" -Class pannerWidgetClass -.IN "pannerWidgetClass" "" -Class Name Panner -.IN "Panner widget" "class name" -Superclass Simple -.sp -.De -.LP -A Panner widget is a rectangle, called the -``canvas,'' on which another rectangle, the ``slider,'' moves in two -dimensions. It is often used with a Porthole widget to move, or -``scroll,'' a third widget in two dimensions, in which case the -slider's size and position gives feedback as to what portion of -the third widget is visible. -.LP -The slider may be scrolled around the canvas by pressing, -dragging, and releasing Button1; the default translation also -enables scrolling via arrow keys and some other keys. While -scrolling is in progress, the application receives notification -through callback procedures. Notification may be done either -continuously whenever the slider moves or discretely whenever the -slider has been given a new location. -.NH 3 -Resources -.LP -When creating a Panner widget instance, the following resources are -retrieved from the argument list or from the resource database: -.LP -.IN "Panner 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 -allowOff AllowOff Boolean False -ancestorSensitive AncestorSensitive Boolean D True -background Background Pixel XtDefaultBackground -backgroundPixmap Pixmap Pixmap XtUnspecifiedPixmap -backgroundStipple BackgroundStipple String NULL -borderColor BorderColor Pixel XtDefaultForeground -borderPixmap Pixmap Pixmap XtUnspecifiedPixmap -borderWidth BorderWidth Dimension 1 -canvasHeight CanvasHeight Dimension 0 -canvasWidth CanvasWidth Dimension 0 -colormap Colormap Colormap Parent's Colormap -cursor Cursor Cursor None -cursorName Cursor String NULL -defaultScale DefaultScale Dimension 8 -depth Depth int C Parent's Depth -destroyCallback Callback XtCallbackList NULL -foreground Foreground Pixel XtDefaultForeground -height Height Dimension A depends on orientation -internalSpace InternalSpace Dimension 4 -international International Boolean C False -lineWidth LineWidth Dimension 0 -mappedWhenManaged MappedWhenManaged Boolean True -pointerColor Foreground Pixel XtDefaultForeground -pointerColorBackground Background Pixel XtDefaultBackground -reportCallback ReportCallback Callback NULL -resize Resize Boolean True -rubberBand RubberBand Boolean False -screen Screen Screen R Parent's Screen -sensitive Sensitive Boolean True -shadowColor ShadowColor Pixel XtDefaultForeground -shadowThickness ShadowThickness Dimension 2 -sliderX SliderX Position 0 -sliderY SliderY Position 0 -sliderHeight SliderHeight Dimension 0 -sliderWidth SliderWidth Dimension 0 -translations Translations TranslationTable See below -width Width Dimension A depends on orientation -x Position Position 0 -y Position Position 0 -.sp 3p -_ -.TE -.Ac -.IP \fBallowOff\fP 1.5i -Whether to allow the edges of the slider to go off the edges of the canvas. -.As -.Bg -.Gp -.IP \fBbackgroundStipple\fP 1.5i -The name of a bitmap pattern to be used as the background for -the area representing the canvas. -.Bc -.Bp -.Bw -.IP \fBcanvasHeight\fP 1.5i -.br -.ns -.IP \fBcanvasWidth\fP 1.5i -The size of the canvas. -.Cm -.Cu -.Cn -.IP \fBdefaultScale\fP 1.5i -The percentage size that the Panner widget should have relative -to the size of the canvas. -.Dp -.Dc -.IP \fBforeground\fP 1.5i -A pixel value which indexes the widget's colormap to derive the color -used to draw the slider. -.Hw -.IP \fBinternalSpace\fP 1.5i -The width of internal border in pixels between a slider representing the -full size of the canvas -and the edge of the Panner widget. -.Ix -.IP \fBlineWidth\fP 1.5i -The width of the lines in the rubberbanding rectangle when rubberbanding -is in effect instead of continuous scrolling. The default is 0. -.Mm -.Pf -.Pb -.IP \fBreportCallback\fP 1.5i -All functions on this callback list are called when the -\fBnotify\fP action is invoked. See the \fBPanner Actions\fP section -for details. -.IP \fBresize\fP 1.5i -Whether or not to resize the panner whenever the canvas size is changed so -that the \fBdefaultScale\fP is maintained. -.IP \fBrubberBand\fP 1.5i -Whether or not scrolling should be discrete (only moving a rubberbanded -rectangle until the scrolling is done) or continuous (moving the slider -itself). This controls whether or not the \fBmove\fP action procedure also -invokes the \fBnotify\fP action procedure. -.Sc -.Se -.IP \fBshadowColor\fP 1.5i -The color of the shadow underneath the slider. -.IP \fBshadowThickness\fP 1.5i -The width of the shadow underneath the slider. -.IP \fBsliderX\fP 1.5i -.br -.ns -.IP \fBsliderY\fP 1.5i -The location of the slider in the coordinates of the canvas. -.IP \fBsliderHeight\fP 1.5i -.br -.ns -.IP \fBsliderWidth\fP 1.5i -The size of the slider. -.Tr -.Xy -.NH 3 -Panner Actions -.IN "Panner widget" "actions" -.LP -The actions supported by the Panner widget are: -.IP \fBstart\fP() 1.5i -This action begins movement of the slider. -.IP \fBstop\fP() 1.5i -This action ends movement of the slider. -.IP \fBabort\fP() 1.5i -This action ends movement of the slider and restores it to the position it -held when the \fBstart\fP action was invoked. -.IP \fBmove\fP() 1.5i -This action moves the outline of the slider (if the \fBrubberBand\fP resource -is True) or the slider itself (by invoking the \fBnotify\fP -action procedure). -.IP \fBpage\fP(\fIxamount\fP,\fIyamount\fP) 1.5i -This action moves the slider by the specified amounts. The format -for the amounts is a signed or unsigned floating-point number (e.g., +1.0 -or \-.5) followed -by either \fBp\fP indicating pages (slider sizes), or \fBc\fP indicating -canvas sizes. Thus, \fIpage(+0,+.5p)\fP represents vertical movement down -one-half the height of the slider and \fIpage(0,0)\fP represents moving to -the upper left corner of the canvas. -.IP \fBnotify\fP() 1.5i -This action informs the application of the slider's current position by -invoking the \fBreportCallback\fP functions registered by the application. -.IP \fBset\fP(\fIwhat\fP,\fIvalue\fP) 1.5i -This action changes the behavior of the Panner. The \fIwhat\fP argument -must currently be the string \fBrubberband\fP and controls the value of -the \fBrubberBand\fP resource. The \fIvalue\fP argument -may have one of the values \fBon\fP, \fBoff\fP, or \fBtoggle\fP. -.LP -.sp -The default bindings for Panner are: -.IN "Panner widget" "default translation table" -.LP -.Ds 0 -.TA .5i 1.75i -.ta .5i 1.75i - <Btn1Down>: start(\|) - <Btn1Motion>: move(\|) - <Btn1Up>: notify(\|) stop(\|) - <Btn2Down>: abort(\|) - <Key>KP_Enter: set(rubberband,toggle) - <Key>space: page(+1p,+1p) - <Key>Delete: page(\-1p,\-1p) - <Key>BackSpace: page(\-1p,\-1p) - <Key>Left: page(\-.5p,+0) - <Key>Right: page(+.5p,+0) - <Key>Up: page(+0,\-.5p) - <Key>Down: page(+0,+.5p) - <Key>Home: page(0,0) -.De -.NH 3 -Panner Callbacks -.IN "Panner widget" "callbacks" -.LP -The functions registered on the \fBreportCallback\fP list are invoked by -the \fBnotify\fP action as follows: -.IN "ReportProc" "" "@DEF@" -.FD 0 -void ReportProc(\fIpanner\fP, \fIclient_data\fP, \fIreport\fP) -.br - Widget \fIpanner\fP; -.br - XtPointer \fIclient_data\fP; -.br - XtPointer \fIreport\fP; /* (XawPannerReport *) */ -.FN -.IP \fIpanner\fP 1i -Specifies the Panner widget. -.IP \fIclient_data\fP 1i -Specifies the client data. -.IP \fIreport\fP 1i -Specifies a pointer to an \fBXawPannerReport\fP structure containing -the location and size of the slider and the size of the canvas. diff --git a/xc/doc/specs/Xaw/Porthole b/xc/doc/specs/Xaw/Porthole deleted file mode 100644 index d01e35fcc..000000000 --- a/xc/doc/specs/Xaw/Porthole +++ /dev/null @@ -1,125 +0,0 @@ -.\" $XConsortium: Porthole,v 1.4 94/05/01 20:44:59 gildea Exp $ -.NH 2 -Porthole Widget -.LP -.XS - Porthole Widget -.XE -.IN "Porthole widget" "" "@DEF@" -.Ds 0 -.TA 2.0i -.ta 2.0i -.sp -Application Header file <X11/Xaw/Porthole.h> -.IN "Porthole.h" "" -Class Header file <X11/Xaw/PortholeP.h> -.IN "PortholeP.h" "" -Class portholeWidgetClass -.IN "portholeWidgetClass" "" -Class Name Porthole -.IN "Porthole widget" "class name" -Superclass Composite -.sp -.De -.LP -The Porthole widget provides geometry management of a list of arbitrary -widgets, only one of which may be managed at any particular time. -The managed child widget is reparented within the porthole and is moved around -by the application (typically under the control of a Panner widget). -.NH 3 -Resources -.LP -When creating a Porthole widget instance, the following resources are -retrieved from the argument list or from the resource database: -.LP -.IN "Porthole 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 -mappedWhenManaged MappedWhenManaged Boolean True -numChildren ReadOnly Cardinal R 0 -reportCallback ReportCallback Callback NULL -screen Screen Screen R Parent's Screen -sensitive Sensitive Boolean True -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 -.Mm -.Nc -.IP \fBreportCallback\fP 1.5i -A list of functions to invoke whenever the managed child widget changes -size or position. -.Sc -.Se -.Tr -.Xy -.NH 3 -Layout Semantics -.IN "Porthole widget" "layout semantics" -.LP -The Porthole widget allows its managed child to request any size -that is as large -or larger than the Porthole itself and any location so long as the child -still obscures all of the Porthole. This widget typically is used with a -Panner widget. -.NH 3 -Porthole Callbacks -.IN "Porthole widget" "callbacks" -.LP -The functions registered on the \fBreportCallback\fP list are invoked whenever -the managed child changes size or position: -.IN "ReportProc" "" "@DEF@" -.FD 0 -void ReportProc(\fIporthole\fP, \fIclient_data\fP, \fIreport\fP) -.br - Widget \fIporthole\fP; -.br - XtPointer \fIclient_data\fP; -.br - XtPointer \fIreport\fP; /* (XawPannerReport *) */ -.FN -.IP \fIporthole\fP 1i -Specifies the Porthole widget. -.IP \fIclient_data\fP 1i -Specifies the client data. -.IP \fIreport\fP 1i -Specifies a pointer to an \fBXawPannerReport\fP structure containing -the location and size of the slider and the size of the canvas. - diff --git a/xc/doc/specs/Xaw/Repeater b/xc/doc/specs/Xaw/Repeater deleted file mode 100644 index f4a15c08a..000000000 --- a/xc/doc/specs/Xaw/Repeater +++ /dev/null @@ -1,184 +0,0 @@ -.\" $XConsortium: Repeater,v 1.6 94/05/01 19:21:21 gildea Exp $ -.NH 2 -Repeater Widget -.XS - Repeater Widget -.XE -.IN "Repeater widget" "" "@DEF@" -.Ds 0 -.TA 2.0i -.ta 2.0i -.sp -Application header file <X11/Xaw/Repeater.h> -.IN "Repeater.h" "" -Class header file <X11/Xaw/RepeaterP.h> -.IN "RepeaterP.h" "" -Class repeaterWidgetClass -.IN "repeaterWidgetClass" "" -Class Name Repeater -.IN "Repeater widget" "class name" -Superclass Command -.sp -.De -.LP -The Repeater widget is a subclass of the Command widget; see the -Command documentation for details. The difference is that the Repeater can call its -registered callbacks repeatedly, at an increasing rate. The default translation -does so for the duration the user holds down pointer button 1 while the pointer -is on the Repeater. -.NH 3 -Resources -.LP -When creating a Repeater widget instance, the following resources are -retrieved from the argument list or from the resource database: -.LP -.IN "Repeater 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 -bitmap Bitmap Pixmap None -borderColor BorderColor Pixel XtDefaultForeground -borderPixmap Pixmap Pixmap XtUnspecifiedPixmap -borderWidth BorderWidth Dimension 1 -callback Callback XtCallbackList NULL -colormap Colormap Colormap Parent's Colormap -cornerRoundPercent CornerRoundPercent Dimension 25 -cursor Cursor Cursor None -cursorName Cursor String NULL -decay Decay Int 5 -depth Depth int C Parent's Depth -destroyCallback Callback XtCallbackList NULL -encoding Encoding UnsignedChar XawTextEncoding8bit -flash Boolean Boolean False -font Font XFontStruct XtDefaultFont -fontSet FontSet XFontSet XtDefaultFontSet -foreground Foreground Pixel XtDefaultForeground -height Height Dimension A graphic height + 2 * \fBinternalHeight\fP -highlightThickness Thickness Dimension A 2 (0 if Shaped) -initialDelay Delay Int 200 -insensitiveBorder Insensitive Pixmap GreyPixmap -internalHeight Height Dimension 2 -internalWidth Width Dimension 4 -international International Boolean C False -justify Justify Justify XtJustifyCenter (center) -label Label String name of widget -leftBitmap LeftBitmap Bitmap None -mappedWhenManaged MappedWhenManaged Boolean True -minimumDelay MinimumDelay Int 10 -pointerColor Foreground Pixel XtDefaultForeground -pointerColorBackground Background Pixel XtDefaultBackground -repeatDelay Delay Int 50 -resize Resize Boolean True -screen Screen Pointer R Parent's Screen -sensitive Sensitive Boolean True -shapeStyle ShapeStyle ShapeStyle Rectangle -startCallback StartCallback Callback NULL -stopCallback StopCallback Callback NULL -translations Translations TranslationTable See below -width Width Dimension A graphic width + 2 * \fBinternalWidth\fP -x Position Position 0 -y Position Position 0 -.sp 3p -_ -.TE -\" Resource Descriptions -.Ac -.As -.Bg -.Gp -.Bm -.Bc -.Bp -.Bw -.Cb -.Cm -.Cr -.Cu -.Cn -.IP \fBdecay\fP 1.5i -The number of milliseconds that should be subtracted from each succeeding -interval while the Repeater button is being held down until the interval -has reached \fBminimumDelay\fP milliseconds. -.Dp -.Dc -.Le -.IP \fBflash\fP 1.5i -Whether or not to flash the Repeater button whenever the timer goes off. -.Lf -.Ls -.Lg -.Hw -.Ht -.IP \fBinitialDelay\fP 1.5i -The number of milliseconds between the beginning of the Repeater button -being held down and the first invocation of the \fBcallback\fP function. -.Ib -.Ih -.In -.Ju -.La -.Ll -.Mm -.IP \fBminimumDelay\fP 1.5i -The minimum time between callbacks in milliseconds. -.Pf -.Pb -.IP \fBrepeatDelay\fP 1.5i -The number of milliseconds between each callback after the first (minus an -increasing number of \fBdecay\fPs). -.Re -.Sc -.Se -.Ss -.IP \fBstartCallback\fP 1.5i -The list of functions to invoke by the \fBstart\fP action (typically -when the Repeater button is first pressed). The callback data parameter -is set to NULL. -.IP \fBstopCallback\fP 1.5i -The list of functions to invoke by the \fBstop\fP action (typically -when the Repeater button is released). The callback data parameter -is set to NULL. -.Tr -.Xy -.NH 3 -Repeater Actions -.IN "Repeater widget" "actions" -.LP -The Repeater widget supports the following actions beyond those of the Command -button: -.IP \fBstart\fP() 1.5i -This invokes the functions on the \fBstartCallback\fP and \fBcallback\fP lists -and sets a timer to go off in \fBinitialDelay\fP milliseconds. The timer -will cause the \fBcallback\fP functions to be invoked with increasing -frequency until the \fBstop\fP action occurs. -.IP \fBstop\fP() 1.5i -This invokes the functions on the \fBstopCallback\fP list and prevents any -further timers from occuring until the next \fBstart\fP action. -.LP -.sp -.IN "Repeater widget" "translation bindings" -The following are the default translation bindings used by the -Repeater widget: -.LP -.Ds 0 -.TA .5i 2.25i -.ta .5i 2.25i - <EnterWindow>: highlight(\|) - <LeaveWindow>: unhighlight(\|) - <Btn1Down>: set(\|) start(\|) - <Btn1Up>: stop(\|) unset(\|) -.De -.LP diff --git a/xc/doc/specs/Xaw/Scrollbar b/xc/doc/specs/Xaw/Scrollbar deleted file mode 100644 index 75064849a..000000000 --- a/xc/doc/specs/Xaw/Scrollbar +++ /dev/null @@ -1,386 +0,0 @@ -.\" $XConsortium: Scrollbar,v 1.27 94/05/01 19:21:14 gildea Exp $ -.NH 2 -Scrollbar Widget -.LP -.XS - Scrollbar Widget -.XE -.IN "Scrollbar widget" "" "@DEF@" -.Ds 0 -.TA 2.0i -.ta 2.0i -.sp -Application header file <X11/Xaw/Scrollbar.h> -.IN "Scrollbar.h" "" -Class header file <X11/Xaw/ScrollbarP.h> -.IN "ScrollbarP.h" "" -Class scrollbarWidgetClass -.IN "scrollbarWidgetClass" "" -Class Name Scrollbar -.IN "Scrollbar widget" "class name" -Superclass Simple -.sp -.De -.LP -A Scrollbar widget is a rectangle, called the ``canvas,'' on -which another rectangle, the ``thumb,'' moves in one -dimension, either vertically or horizontally. A Scrollbar -can be used alone, as a value generator, or it can be used -within a composite widget (for example, a Viewport). When a -Scrollbar is used to move, or ``scroll,'' the contents of -another widget, the size and the position of the thumb usually give -feedback as to what portion of the other widget's contents -are visible. -.LP -Each pointer button invokes a specific action. Pointer -buttons 1 and 3 do not move the thumb automatically. -Instead, they return the pixel position of the cursor on the -scroll region. When pointer button 2 is clicked, the thumb -moves to the current pointer position. When pointer button -2 is held down and the pointer is moved, the thumb follows -the pointer. -.LP -The pointer cursor in the scroll region changes depending on the current -action. When no pointer button is pressed, the cursor appears as a -double-headed arrow that points in the direction that scrolling can -occur. When pointer button 1 or 3 is pressed, the cursor appears as a -single-headed arrow that points in the logical direction that the thumb -will move. When pointer button 2 is pressed, the cursor -appears as an arrow that points to the top or the left of the thumb. -.LP -When the user scrolls, the application receives notification -through callback procedures. For both discrete scrolling actions, the -callback returns the Scrollbar widget, the client_data, and the pixel -position of the pointer when the button was released. For continuous -scrolling, the callback routine returns the scroll bar widget, the -client data, and the current relative position of the thumb. When the -thumb is moved using pointer button 2, the callback procedure is invoked -continuously. When either button 1 or 3 is pressed, the callback -procedure is invoked only when the button is released and the client -callback procedure is responsible for moving the thumb. -.NH 3 -Resources -.LP -When creating a Scrollbar widget instance, the following resources are -retrieved from the argument list or from the resource database: -.LP -.IN "Scrollbar 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 -colormap Colormap Colormap parent's Colormap -cursor Cursor Cursor None -cursorName Cursor String NULL -depth Depth int C parent's Depth -destroyCallback Callback XtCallbackList NULL -foreground Foreground Pixel XtDefaultForeground -height Height Dimension A depends on orientation -insensitiveBorder Insensitive Pixmap GreyPixmap -international International Boolean C False -jumpProc Callback XtCallbackList NULL -length Length Dimension 1 -mappedWhenManaged MappedWhenManaged Boolean True -minimumThumb MinimumThumb Dimension 7 -orientation Orientation Orientation XtorientVertical (vertical) -pointerColor Foreground Pixel XtDefaultForeground -pointerColorBackground Background Pixel XtDefaultBackground -screen Screen Screen R parent's Screen -scrollDCursor Cursor Cursor XC_sb_down_arrow -scrollHCursor Cursor Cursor XC_sb_h_double_arrow -scrollLCursor Cursor Cursor XC_sb_left_arrow -scrollProc Callback XtCallbackList NULL -scrollRCursor Cursor Cursor XC_sb_right_arrow -scrollUCursor Cursor Cursor XC_sb_up_arrow -scrollVCursor Cursor Cursor XC_sb_v_arrow -sensitive Sensitive Boolean True -shown Shown Float 0.0 -thickness Thickness Dimension 14 -thumb Thumb Bitmap GreyPixmap -thumbProc Callback XtCallbackList NULL -topOfThumb TopOfThumb Float 0.0 -translations Translations TranslationTable See below -width Width Dimension A depends on orientation -x Position Position 0 -y Position Position 0 -.sp 3p -_ -.TE -.Ac -.As -.Bg -.Gp -.Bc -.Bp -.Bw -.Cm -.Cu -.Cn -.Dp -.Dc -.IP \fBforeground\fP 1.5i -A pixel value which indexes the widget's colormap to derive the color -used to draw the thumb. -.Hw -.Ib -.Ix -.IP \fBjumpProc\fP 1.5i -All functions on this callback list are called when the -\fBNotifyThumb\fP action is invoked. See the \fBScrollbar -Actions\fP section for details. -.IP \fBlength\fP 1.5i -The height of a vertical scrollbar or the width of a horizontal scrollbar. -.Mm -.IP \fBminimumThumb\fP 1.5i -The smallest size, in pixels, to which the thumb can shrink. -.IP \fBorientation\fP 1.5i -The orientation is the direction that the thumb will be allowed to move. -This value can be either \fBXtorientVertical\fP or -\fBXtorientHorizontal\fP. -.IN "XtorientVertical" "" -.IN "XtorientHorizontal" "" -.IN "conversions" "Orientation" -.Rs "vertical \fPand\fB horizontal" -.Pf -.Pb -.Sc -.IP \fBscrollDCursor\fP 1.5i -This cursor is used when scrolling backward in a vertical scrollbar. -.IP \fBscrollHCursor\fP 1.5i -This cursor is used when a horizontal scrollbar is inactive. -.IP \fBscrollLCursor\fP 1.5i -This cursor is used when scrolling forward in a horizontal scrollbar. -.IP \fBscrollProc\fP 1.5i -All functions on this callback list may be called when the -\fBNotifyScroll\fP action is invoked. See the \fBScrollbar -Actions\fP section for details. -.IP \fBscrollRCursor\fP 1.5i -This cursor is used when scrolling backward in a horizontal scrollbar, -or when thumbing a vertical scrollbar. -.IP \fBscrollUCursor\fP 1.5i -This cursor is used when scrolling forward in a vertical scrollbar, or when -thumbing a horizontal scrollbar. -.IP \fBscrollVCursor\fP 1.5i -This cursor is used when a vertical scrollbar is inactive. -.Se -.IP \fBshown\fP 1.5i -This is the size of the thumb, expressed as a percentage (0.0 - 1.0) -of the length of the scrollbar. -.IP \fBthickness\fP 1.5i -The width of a vertical scrollbar or the height of a horizontal scrollbar. -.IP \fBthumb\fP 1.5i -This pixmap is used to tile (or stipple) the thumb of the scrollbar. If -no tiling is desired, then set this resource to \fBNone\fP. This -resource will accept either a bitmap or a pixmap that is the same depth -as the window. The resource converter for this resource constructs -bitmaps from the contents of files. (See \fBConverting Bitmaps\fP for -details.) -.IP \fBtopOfThumb\fP 1.5i -The location of the top of the thumb, as a percentage (0.0 - 1.0) -of the length of the scrollbar. This resource was called \fBtop\fP in -previous versions of the Athena widget set. The name collided with the -a Form widget constraint resource, and had to be changed. -.Tr -.Xy -.NH 3 -Scrollbar Actions -.IN "Scrollbar widget" "actions" -.LP -The actions supported by the Scrollbar widget are: -.IP \fBStartScroll\fP(\fIvalue\fP) 1.5i -The possible \fIvalues\fP are Forward, Backward, or Continuous. -This must be the first action to begin a new movement. -.IP \fBNotifyScroll\fP(\fIvalue\fP) 1.5i -The possible \fIvalues\fP are Proportional or FullLength. If the -argument to StartScroll was Forward or Backward, NotifyScroll executes -the \fBscrollProc\fP callbacks and passes either; the position of the -pointer, if \fIvalue\fP is Proportional, or the full length of the -scroll bar, if \fIvalue\fP is FullLength. If the argument to -StartScroll was Continuous, NotifyScroll returns without executing any -callbacks. -.IP \fBEndScroll\fP(\^) 1.5i -This must be the last action after a movement is complete. -.IP \fBMoveThumb\fP(\^) 1.5i -Repositions the Scrollbar's thumb to the current pointer location. -.IP \fBNotifyThumb\fP(\^)\ \ \ 1.5i -Calls the -.PN jumpProc -callbacks and passes the relative position of the -pointer as a percentage of the scroll bar length. -.LP -.sp -The default bindings for Scrollbar are: -.IN "Scrollbar widget" "default translation table" -.LP -.Ds 0 -.TA .5i 1.75i -.ta .5i 1.75i - <Btn1Down>: StartScroll(Forward) - <Btn2Down>: StartScroll(Continuous) MoveThumb(\|) NotifyThumb(\|) - <Btn3Down>: StartScroll(Backward) - <Btn2Motion>: MoveThumb(\|) NotifyThumb(\|) - <BtnUp>: NotifyScroll(Proportional) EndScroll(\|) -.De -.LP -.sp -Examples of additional bindings a user might wish to specify in a -resource file are: -.LP -.Ds 0 -.TA .5i 2.25i -.ta .5i 2.25i -*Scrollbar.Translations: \\ - ~Meta<Key>space: StartScroll(Forward) NotifyScroll(FullLength) \\n\\ - Meta<Key>space: StartScroll(Backward) NotifyScroll(FullLength) \\n\\ - EndScroll(\|) -.De -.NH 3 -Scrollbar Callbacks -.IN "Scrollbar widget" "callbacks" -.LP -There are two callback lists provided by the Scrollbar widget. -The procedural interface for these functions is described here. -.LP -The calling interface to the \fBscrollProc\fP callback procedure is: -.IN "ScrollProc" "" "@DEF@" -.FD 0 -void ScrollProc(\fIscrollbar\fP, \fIclient_data\fP, \fIposition\fP) -.br - Widget \fIscrollbar\fP; -.br - XtPointer \fIclient_data\fP; -.br - XtPointer \fIposition\fP; /* int */ -.FN -.IP \fIscrollbar\fP 1i -Specifies the Scrollbar widget. -.IP \fIclient_data\fP 1i -Specifies the client data. -.IP \fIposition\fP 1i -Specifies a pixel position in integer form. -.LP -The \fBscrollProc\fP callback is used for incremental scrolling -and is called by the \fBNotifyScroll\fP action. -The position argument is a signed quantity and should be cast to an int -when used. Using the default button bindings, button 1 returns a -positive value, and button 3 returns a negative value. In both cases, -the magnitude of the value is the distance of the pointer in -pixels from the top (or left) of the Scrollbar. The value will never -be greater than the length of the Scrollbar. -.LP -.sp -The calling interface to the \fBjumpProc\fP callback procedure is: -.IN "jumpProc" "" "@DEF@" -.FD 0 -void JumpProc(\fIscrollbar\fP, \fIclient_data\fP, \fIpercent\fP) -.br - Widget \fIscrollbar\fP; -.br - XtPointer \fIclient_data\fP; -.br - XtPointer \fIpercent_ptr\fP; /* float* */ -.FN -.IP \fIscrollbar\fP 1i -Specifies the ID of the scroll bar widget. -.IP \fIclient_data\fP 1i -Specifies the client data. -.IP \fIpercent_ptr\fP 1i -Specifies the floating point position of the thumb (0.0 \- 1.0). -.LP -The \fBjumpProc\fP callback is used to implement smooth scrolling and -is called by the \fBNotifyThumb\fP action. Percent_ptr must be cast -to a pointer to float before use; i.e. -.LP -.Ds 0 -.TA .5i -.ta .5i - float percent = *(float*)percent_ptr; -.De -.LP -With the default button bindings, button 2 moves the thumb interactively, -and the \fBjumpProc\fP is called on each new position of the pointer, -while the pointer button remains down. The value specified by -\fIpercent_ptr\fP is the current location of the thumb (from the top or -left of the Scrollbar) expressed as a percentage of the length of the -Scrollbar. -.NH 3 -Convenience Routines -.LP -.IN "Scrollbar widget" "setting thumb values" -To set the position and length of a Scrollbar thumb, use -.PN XawScrollbarSetThumb . -.IN "XawScrollbarSetThumb" "" "@DEF@" -.FD 0 -void XawScrollbarSetThumb(\fIw\fP, \fItop\fP, \fIshown\fP) -.br - Widget \fIw\fP; -.br - float \fItop\fP; -.br - float \fIshown\fP; -.FN -.IP \fIw\fP 1i -Specifies the Scrollbar widget. -.IP \fItop\fP 1i -Specifies the position of the top of the thumb as a fraction of the -length of the Scrollbar. -.IP \fIshown\fP 1i -Specifies the length of the thumb as a fraction of the total length -of the Scrollbar. -.LP -.PN XawScrollbarThumb -moves the visible thumb to a new position (0.0 \- 1.0) and length (0.0 \- 1.0). -Either the top or shown arguments can be specified as \-1.0, -in which case the current value is left unchanged. -Values greater than 1.0 are truncated to 1.0. -.LP -If called from \fBjumpProc\fP, \fBXawScrollbarSetThumb\fP has no effect. -.NH 3 -Setting Float Resources -.IN "float resources" "setting" -.LP -The \fBshown\fP and \fBtopOfThumb\fP resources are of type -\fIfloat\fP. These resources can be difficult to get into an -argument list. The reason is that C performs an automatic cast of -the float value to an integer value, usually truncating the important -information. The following code fragment is one portable method of -getting a float into an argument list. -.sp -.Ds 0 -.SM -.TA 1i 2i -.ta 1i 2i - top = 0.5; - if (sizeof(float) > sizeof(XtArgVal)) { - /* - \ * If a float is larger than an XtArgVal then pass this - \ * resource value by reference. - \ */ - XtSetArg(args[0], XtNshown, &top); - } - else { - /* - \ * Convince C not to perform an automatic conversion, which - \ * would truncate 0.5 to 0. - \ */ - XtArgVal * l_top = (XtArgVal *) ⊤ - XtSetArg(args[0], XtNshown, *l_top); - } -.NL -.De -.sp diff --git a/xc/doc/specs/Xaw/Simple b/xc/doc/specs/Xaw/Simple deleted file mode 100644 index 6993983bc..000000000 --- a/xc/doc/specs/Xaw/Simple +++ /dev/null @@ -1,95 +0,0 @@ -.\" $XConsortium: Simple,v 1.19 94/05/01 19:21:02 gildea Exp $ -.NH 2 -Simple Widget -.XS - Simple Widget -.XE -.IN "Simple widget" "" "@DEF@" -.Ds 0 -.TA 2.0i -.ta 2.0i -.sp -Application Header file <Xaw/Simple.h> -.IN "Simple.h" "" -Class Header file <Xaw/SimpleP.h> -.IN "SimpleP.h" "" -Class simpleWidgetClass -.IN "simpleWidgetClass" -Class Name Simple -.IN "Simple widget" "class name" -Superclass Core -.sp -.De -.LP -The Simple widget is not very useful by itself, as it has no semantics -of its own. It main purpose is to be used as a common superclass for -the other \fIsimple\fP Athena widgets. This widget adds six resources -to the resource list provided by the Core widget and its superclasses. -.NH 3 -Resources -.LP -When creating a Simple widget instance, the following resources are -retrieved from the argument list or from the resource database: -.LP -.IN "Simple 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 -colormap Colormap Colormap Parent's Colormap -cursor Cursor Cursor None -cursorName Cursor String NULL -depth Depth int C Parent's Depth -destroyCallback Callback XtCallbackList NULL -height Height Dimension 0 -insensitiveBorder Insensitive Pixmap GreyPixmap -international International Boolean C False -mappedWhenManaged MappedWhenManaged Boolean True -pointerColor Foreground Pixel XtDefaultForeground -pointerColorBackground Background Pixel XtDefaultBackground -screen Screen Screen R Parent's Screen -sensitive Sensitive Boolean True -translations Translations TranslationTable NULL -width Width Dimension 0 -x Position Position 0 -y Position Position 0 -.sp 3p -_ -.TE -.Ac -.As -.Bg -.Gp -.Bc -.Bp -.Bw -.Cm -.Cu Bold -.Cn Bold -.Dp -.Dc -.Hw -.Ib Bold -.Ix Bold -.Mm -.Pf Bold -.Pb Bold -.Sc -.Se -.Tr -.Xy diff --git a/xc/doc/specs/Xaw/SimpleMenu b/xc/doc/specs/Xaw/SimpleMenu deleted file mode 100644 index a4aa97d0c..000000000 --- a/xc/doc/specs/Xaw/SimpleMenu +++ /dev/null @@ -1,315 +0,0 @@ -.\" $XConsortium: SimpleMenu,v 1.4 94/05/01 19:21:18 gildea Exp $ -.NH 2 -SimpleMenu Widget -.XS - SimpleMenu Widget -.XE -.IN "SimpleMenu widget" "" "@DEF@" -.Ds 0 -.TA 2.0i -.ta 2.0i -.sp -Application Header file <X11/Xaw/SimpleMenu.h> -.IN "SimpleMenu.h" "" -Class Header file <X11/Xaw/SimpleMenP.h> -.IN "SimpleMenP.h" "" -Class simpleMenuWidgetClass -.IN "simpleMenuWidgetClass" "" -Class Name SimpleMenu -.IN "SimpleMenu widget" "class name" -Superclass OverrideShell -.sp -.De -.LP -The SimpleMenu widget is a container for the menu entries. It is a -direct subclass of shell, and is should be created with -\fBXtCreatePopupShell\fP, not \fBXtCreateManagedWidget\fP. This is the -only part of the menu that -actually is associated with a window. The SimpleMenu serves as the glue to bind -the individual menu entries together into a menu. -.NH 3 -Resources -.LP -.IN "SimpleMenu widget" "resources" -.LP -The resources associated with the SimpleMenu widget control aspects -that will affect the entire menu. -.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 -accelerators Accelerators AcceleratorTable NULL -ancestorSensitive AncestorSensitive Boolean D True -allowShellResize AllowShellResize Boolean True -background Background Pixel XtDefaultBackground -backgroundPixmap Pixmap Pixmap XtUnspecifiedPixmap -backingStore BackingStore BackingStore see below -borderColor BorderColor Pixel XtDefaultForeground -borderPixmap Pixmap Pixmap XtUnspecifiedPixmap -borderWidth BorderWidth Dimension 1 -bottomMargin VerticalMargins Dimension 0 -children ReadOnly WidgetList R NULL -createPopupChildProc CreatePopupChildProc Function NULL -colormap Colormap Colormap Parent's Colormap -cursor Cursor Cursor None -depth Depth int C Parent's Depth -destroyCallback Callback XtCallbackList NULL -geometry Geometry String NULL -height Height Dimension Enough space to contain all entries -label Label String NULL -labelClass LabelClass Pointer SmeBSBObjectClass -mappedWhenManaged MappedWhenManaged Boolean True -menuOnScreen MenuOnScreen Boolean True -numChildren ReadOnly Cardinal R 0 -overrideRedirect OverrideRedirect Boolean True -popdownCallback Callback XtCallbackList NULL -popupCallback Callback XtCallbackList NULL -popupOnEntry PopupOnEntry Widget A Label or first entry -rowHeight RowHeight Dimension 0 -saveUnder SaveUnder Boolean False -screen Screen Screen R Parent's Screen -sensitive Sensitive Boolean True -topMargin VerticalMargins Dimension 0 -translations Translations TranslationTable See below -visual Visual Visual CopyFromParent -width Width Dimension Width of widest entry -x Position Position 0 -y Position Position 0 -.sp 3p -_ -.TE -.Ac -.As -.IP \fBbackingStore\fP 1.5i -.IN "conversions" "BackingStore" -Determines what type of backing store will be used for the menu. Legal -values for this resource are \fBNotUseful\fP, \fBWhenMapped\fP, and -\fBAlways\fP. These values are the backing-store integers defined in -<X11/X.h>. -.Rs "notUseful, whenMapped, always, \fPand\fP default" -If \fBdefault\fP is specified (the default behavior) the server will use -whatever it thinks is appropriate. -.Bg -.Gp -.Bc -.Bp -.Bw -.IP \fBbottomMargin\fP 1.5i -.br -.ns -.IP \fBtopMargin\fP 1.5i -The amount of space between the top or bottom of the menu and the menu entry -closest to that edge. -.Ch -.Cm -.IP \fBcursor\fP 1.5i -The shape of the mouse pointer whenever it is in this widget. -.Dp -.Dc -.IP geometry 1.5i -If this resource is specified it will override the x, y, width and -height of this widget. The format of this string is -[<\fIwidth\fP>x<\fIheight\fP>][{+ -} <\fIxoffset\fP> {+ -}<\fIyoffset\fP>]. -.Hw -.IP \fBlabel\fP 1.5i -This label will be placed at the top of the SimpleMenu, and may not be -highlighted. The name of the -label object is \fBmenuLabel\fP. Using this name it is possible to -modify the label's attributes through the resource database. When the label -is created, the \fBlabel\fP is hard coded to the value of \fBlabel\fP, and -\fBjustify\fP is hard coded as \fBXtJustifyCenter\fP. -.IP \fBlabelClass\fP 1.5i -Specifies the type of Sme object created as the menu label. -.Mm -.IP \fBmenuOnScreen\fP 1.5i -If the menu is automatically positioned under the cursor with the -\fBXawPositionSimpleMenu\fP action, and this resource is \fBTrue\fP, -then the menu will always be fully visible on the screen. -.Nc -.IP overrideRedirect 1.5i -Determines the value of the override_redirect attribute of the -SimpleMenu's window. The override_redirect attribute of a window -determines whether or not a window manager may interpose itself between -this window and the root window of the display. For more information -see the \fIInterclient Communications Conventions Manual\fP. -.IP popdownCallback 1.5i -.br -.ns -.IP popupCallback 1.5i -These callback functions are called by the Xt Intrinsics whenever the -shell is popped up or down (See \fI\*(xT\fP for details). -.IP \fBpopupOnEntry\fP 1.5i -The \fBXawPositionSimpleMenu\fP action will, by default, popup the -SimpleMenu with its label (or first entry) directly under the -pointer. To popup the menu under -another entry, set this resource to the menu entry that should be -under the pointer, when the menu is popped up. This allows the -application to offer the user a default menu entry that can be selected -with out moving the pointer. -.IP \fBrowHeight\fP 1.5i -If this resources is zero (the default) then each menu entry will be -given its desired height. If this resource has any other value then -all menu entries will be forced to be \fBrowHeight\fP pixels high. -.IP saveUnder 1.5i -If this is \fBTrue\fP then save unders will be active on the menu's window. -.Sc -.Se -.Tr -.Xy -.NH 3 -SimpleMenu Actions -.IN "SimpleMenu widget" "actions" -.LP -The SimpleMenu widget supports the following actions: -.IP \(bu 5 -Switching the entry under the mouse pointer between -the foreground and background colors with \fBhighlight\fP -and \fBunhighlight\fP -.IP \(bu 5 -Processing menu entry callbacks with \fBnotify\fP -.sp -.LP -.IN "SimpleMenu widget" "default translations" -The following are the default translation bindings used -by the SimpleMenu widget: -.LP -.sp -.Ds 0 -.TA .5i 2.25i -.ta .5i 2.25i - <EnterWindow>: highlight(\|) - <LeaveWindow>: unhighlight(\|) - <BtnMotion>: highlight(\|) - <BtnUp>: MenuPopdown(\|) notify(\|) unhighlight(\|) -.De -.sp -.LP -.IN "SimpleMenu widget" "MenuPopdown routine" -The user can pop down the menu without activating any of the callback -functions by releasing the pointer button when no menu item is -highlighted. -.sp -.LP -The full list of actions supported by SimpleMenu is: -.IP \fBhighlight\fP() 1.5i -Highlight the menu entry that is currently under the pointer. -Only a item that is highlighted will be notified when the \fBnotify\fP -action is invoked. The look of a highlighted entry is determined by -the menu entry. -.IP \fBunhighlight\fP(\|) 1.5i -Unhighlights the currently highlighted menu item, and returns it to -its normal look. -.IP \fBnotify\fP(\|) 1.5i -Notifies the menu entry that is currently highlighted that is has been -selected. It is the responsibility of the menu entry to take the -appropriate action. -.IP \fBMenuPopdown\fP(\fImenu\fP) -This action is defined in \fI\*(xT\fP. -.IN "SimpleMenu widget" "MenuPopdown routine" -.NH 3 -Positioning the SimpleMenu -.IN "XawPositionSimpleMenu" "" "@DEF@" -.IN "SimpleMenu widget" "positioning" "@DEF@" -.LP -If the SimpleMenu widget is to be used as a pulldown menu then the -MenuButton widget, or some other outside means should be used to place -the menu when it is popped up. -.LP -If popup menus are desired it will be necessary to add the -\fBXawPositionSimpleMenu\fP and \fBMenuPopup\fP actions to the -translation table of the widget that will be popping up the menu. The -\fBMenuPopup\fP action is described in \fI\*(xT\fP. -\fBXawPositionSimpleMenu\fP is a global action procedure registered by -the SimpleMenu widget when the first one is created or the convenience -routine \fBXawSimpleMenuAddGlobalActions\fP is called. -.LP -Translation writers should be aware that Xt does not register grabs on -``don't care'' modifiers, and therefore the left hand side of the -production should be written to exclude unspecified modifiers. -For example these are the translations needed to popup some of -\fBxterm's\fP menus: -.sp -.LP -.Ds 0 -.TA .5i 2.25i -.ta .5i 2.25i - !Ctrl<Btn1Down>: XawPositionSimpleMenu(xterm) MenuPopup(xterm) - !Ctrl<Btn2Down>: XawPositionSimpleMenu(modes) MenuPopup(modes) -.De -.sp 1 -.LP -.IP \fBXawPositionSimpleMenu\fP(\fImenu\fP) 2.25i -The \fBXawPositionSimpleMenu\fP routine will search for the menu name -passed to it using \fBXtNameToWidget\fP starting with the widget -invoking the action as the reference widget. If it is unsuccessful it -will continue up the widget tree using each of the invoking widget's -ancestors as the reference widget. If it is still unsuccessful it will -print a warning message and give up. \fBXawPositionSimpleMenu\fP will -position the menu directly under the pointer cursor. The menu will be -placed so that the pointer cursor is centered on the entry named by the -\fBpopupOnEntry\fP resource. If the \fBmenuOnScreen\fP resource is -\fBTrue\fP then the menu will always be fully visible on the screen. -.NH 3 -Convenience Routines -.NH 4 -Registering the Global Action Routines -.LP -.IN "XawPositionSimpleMenu" "" -The \fBXawPositionSimpleMenu\fP action routine may often be invoked -before any menus have been created. This can occur when an -application uses dynamic menu creation. In these cases an application will -need to register this global action routine by calling -\fBXawSimpleMenuAddGlobalActions\fP: -.IN "XawSimpleMenuAddGlobalActions" "" "@DEF@" -.FD 0 -void XawSimpleMenuAddGlobalActions(\fIapp_con\fP) -.br - XtAppContext \fIapp_con\fP; -.FN -.IP \fIapp_con\fP 1i -Specifies the application context in which this action should be registered. -.LP -This function need only be called once per application and must be -called before any widget that uses \fBXawPositionSimpleMenu\fP action -is realized. -.NH 4 -Getting and Clearing the Current Menu Entry -.LP -To get the currently highlighted menu entry use -\fBXawSimpleMenuGetActiveEntry\fP: -.IN "XawSimpleMenuGetActiveEntry" "" "@DEF@" -.FD 0 -Widget XawSimpleMenuGetActiveEntry(\fIw\fP) -.br - Widget \fIw\fP; -.FN -.IP \fIw\fP 1i -Specifies the SimpleMenu widget. -.LP -This function returns the menu entry that is -currently highlighted, or NULL if no entry is highlighted. -.LP -.sp -To clear the SimpleMenu widget's internal information about the -currently highlighted menu entry use -\fBXawSimpleMenuClearActiveEntry\fP: -.IN "XawSimpleMenuClearActiveEntry" "" "@DEF@" -.FD 0 -Widget XawSimpleMenuClearActiveEntry(\fIw\fP) -.br - Widget \fIw\fP; -.FN -.IP \fIw\fP 1i -Specifies the SimpleMenu widget. -.LP -This function unsets all internal references to the currently -highlighted menu entry. It does not \fIunhighlight\fP or otherwise -alter the appearance of the active entry. This function is primarily -for use by implementors of menu entries. diff --git a/xc/doc/specs/Xaw/Sme b/xc/doc/specs/Xaw/Sme deleted file mode 100644 index 40f69a46f..000000000 --- a/xc/doc/specs/Xaw/Sme +++ /dev/null @@ -1,106 +0,0 @@ -.\" $XConsortium: Sme,v 1.15 94/05/01 19:20:59 gildea Exp $ -.NH 2 -Sme Object -.LP -.XS - Sme Object -.XE -.IN "Sme object" "" "@DEF@" -.sp -.Ds 0 -.TA 2.0i -.ta 2.0i -Application Header file <X11/Xaw/Sme.h> -.IN "Sme.h" "" -Class Header file <X11/Xaw/SmeP.h> -.IN "SmeP.h" "" -Class smeObjectClass -.IN "smeObjectClass" "" -Class Name Sme -.IN "Sme object" "class name" -Superclass RectObj -.De -.sp -.LP -The Sme object is the base class for all menu entries. While this -object is mainly intended to be subclassed, it may be used in a menu to -add blank space between menu entries. -.NH 3 -Resources -.IN "SmeLine object" "resources" -.LP -The resources associated with the SmeLine object are defined in this -section, and affect only the single menu entry specified by this object. -There are no new resources added for this class, as it picks up all its -resources from the RectObj class. -.TS H -lw(1.5i) lw(1i) lw(1i) lw(.5i) lw(2i). -_ -.sp 3p -.TB -Name Class Type Notes Default Value -.sp 3p -_ -.TH -.R -.sp 3p -ancestorSensitive AncestorSensitive Boolean True -callback Callback XtCallbackList NULL -destroyCallback Callback XtCallbackList NULL -height Height Dimension 0 -international International Boolean C False -sensitive Sensitive Boolean True -width Width Dimension 1 -.sp 3p -_ -.TE -.As -.Dc -.Hw -Keep in mind that the SimpleMenu widget will force all menu items to -be the width of the widest entry. -.Ix Bold -.Se -.NH 3 -Subclassing the Sme Object -.IN "Sme object" "subclassing" "@DEF" -.LP -.sp -To Create a new Sme object \fIclass\fP you will need to define three class methods. -These methods allow the SimpleMenu to highlight and unhighlight the -menu entry as the pointer cursor moves over it, as well as notify the -entry when the user has selected it. All of -these methods may be inherited from the Sme object, although the default -semantics are not very interesting. -.IP \fBHighlight\fP(\|) 1i -.IN "Sme object" "Highlight method" -Called to put the menu entry into the highlighted state. -.IP \fBUnhighlight\fP(\|) 1i -.IN "Sme object" "Unhighlight method" -Called to return the widget to its normal (unhighlighted) state. -.IP \fBNotify\fP(\|) -.IN "Sme object" "Notify method" -Called when the user selects this menu entry. -.LP -.sp -Other then these methods, creating a new object -is straight forward. Here is some information that may help you -avoid some common mistakes. -.IP 1) 3n -Objects can be zero pixels high. -.IP 2) 3n -Objects draw on their parent's window, therefore the Drawing dimensions -are different from those of widgets. For instance, y locations vary -from \fBy\fP to \fBy + height\fP, not \fB0\fP to \fBheight\fP. -.IP 3) 3n -XtSetValues calls may come from the application while the Sme is highlighted, -and if the SetValues method returns True, will result in an expose event. -The SimpleMenu may later call the menu entry's \fBunhighlight\fP -procedure. However, due to the asynchronous nature of -X, the expose event generated by \fBXtSetValues\fP will come \fIafter\fP -this unhighlight. -.IP 4) 3n -Remember that your subclass of the Sme does not own the -window. Share the space with other menu entries, and refrain -from drawing outside the subclass's own section of the menu. - diff --git a/xc/doc/specs/Xaw/SmeBSB b/xc/doc/specs/Xaw/SmeBSB deleted file mode 100644 index 4c9993e73..000000000 --- a/xc/doc/specs/Xaw/SmeBSB +++ /dev/null @@ -1,125 +0,0 @@ -.\" $XConsortium: SmeBSB,v 1.12 94/05/01 19:20:59 gildea Exp $ -.NH 2 -SmeBSB Object -.LP -.XS - SmeBSB Object -.XE -.IN "SmeBSB object" "" "@DEF@" -.Ds 0 -.TA 2.0i -.ta 2.0i -.sp -Application Header file <X11/Xaw/SmeBSB.h> -.IN "SmeBSB.h" "" -Class Header file <X11/Xaw/SmeBSBP.h> -.IN "SmeBSBP.h" "" -Class smeBSBObjectClass -.IN "smeBSBObjectClass" "" -Class Name SmeBSB -.IN "SmeBSB object" "class name" -Superclass Sme -.sp -.De -.LP -The SmeBSB object is used to create a menu entry that contains a string, -and optional bitmaps in its left and right margins. Since each menu -entry is an independent object, the application is able to change the -font, color, height, and other attributes of the menu entries, on an -entry by entry basis. The format of the string may either be the encoding -of the 8 bit \fBfont\fP utilized, or in a multi-byte encoding for use with a -\fBfontSet\fP. -.NH 3 -Resources -.IN "SmeBSB object" "resources" -.LP -The resources associated with the SmeBSB object are defined in this section, -and affect only the single menu entry specified by this object. -.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 -ancestorSensitive AncestorSensitive Boolean D True -callback Callback Callback NULL -destroyCallback Callback XtCallbackList NULL -font Font FontStruct XtDefaultFont -fontSet FontSet XFontSet XtDefaultFontSet -foreground Foreground Pixel XtDefaultForeground -height Height Dimension A Font height + \fBvertSpace\fP -international International Boolean C False -justify Justify Justify XtjustifyLeft -label Label String NULL -leftBitmap LeftBitmap Pixmap XtUnspecifiedPixmap -leftMargin leftMargin Dimension 4 -rightBitmap RightBitmap Pixmap XtUnspecifiedPixmap -rightMargin rightMargin Dimension 4 -sensitive Sensitive Boolean True -vertSpace VertSpace int 25 -width Width Dimension A TextWidth + margins -.sp 3p -_ -.TE -.As -.IP \fBcallback\fP 1.5i -All callback functions on this list are called when the SimpleMenu -\fInotifies\fP this entry that the user has selected it. -.Dc -.IP \fBfont\fP 1.5i -The text font to use when displaying the \fBlabel\fP, when the -\fBinternational\fP resource is \fBfalse\fP. -.IP \fBfontSet\fP 1.5i -The text font set to use when displaying the \fBlabel\fP, when the -\fBinternational\fP resource is \fBtrue\fP. -.IP \fBforeground\fP 1.5i -A pixel value which indexes the SimpleMenu's colormap to derive the -foreground color of the menu entry's window. This color is also -used to render all 1's in the left and right \fBbitmaps\fP. -.Hw -Keep in mind that the SimpleMenu widget will force the width of all -menu entries to be the width of the longest entry. -.In -.IP \fBjustify\fP 1.5i -How the label is to be rendered between the left and right margins when -the space is wider than the actual text. This resource may be -specified with the values \fBXtJustifyLeft\fP, \fBXtJustifyCenter\fP, -or \fBXtJustifyRight\fP. When specifying the justification from a -resource file the values \fBleft\fP, \fBcenter\fP, or \fBright\fP may be -used. -.IP \fBlabel\fP 1.5i -This is a the string that will be displayed in the menu entry. The -exact location of this string within the bounds of the menu entry is -controlled by the \fBleftMargin\fP, \fBrightMargin\fP, \fBvertSpace\fP, -and \fBjustify\fP resources. -.IP \fBleftBitmap\fP 1.5i -.br -.ns -.IP \fBrightBitmap\fP 1.5i -This is a name of a bitmap to display in the left or right margin of the -menu entry. All 1's in the bitmap will be rendered in the foreground -color, and all 0's will be drawn in the background color of the -SimpleMenu widget. It is the -programmers' responsibility to make sure that the menu entry is tall -enough, and the appropriate margin wide enough to accept the bitmap. -If care is not taken the bitmap may extend into another menu entry, or -into this entry's label. -.IP \fBleftMargin\fP 1.5i -.br -.ns -.IP \fBrightMargin\fP 1.5i -This is the amount of space (in pixels) that will be left between the -edge of the menu entry and the label string. -.Se -.IP \fBvertSpace\fP 1.5i -This is the amount of vertical padding, expressed as a percentage of -the height of the font, that is to be placed around the label of a -menu entry.. The label and bitmaps are always centered vertically -within the menu. The default value for this -resource (25) causes the default height to be 125% of the height of the -font. diff --git a/xc/doc/specs/Xaw/SmeLine b/xc/doc/specs/Xaw/SmeLine deleted file mode 100644 index f8d39549c..000000000 --- a/xc/doc/specs/Xaw/SmeLine +++ /dev/null @@ -1,72 +0,0 @@ -.\" $XConsortium: SmeLine,v 1.11 94/05/01 19:21:11 gildea Exp $ -.NH 2 -SmeLine Object -.LP -.XS - SmeLine Object -.XE -.IN "SmeLine object" "" "@DEF@" -.sp -.Ds 0 -.TA 2.0i -.ta 2.0i -Application Header file <X11/Xaw/SmeLine.h> -.IN "SmeLine.h" "" -Class Header file <X11/Xaw/SmeLineP.h> -.IN "SmeLineP.h" "" -Class smeLineObjectClass -.IN "smeLineObjectClass" "" -Class Name SmeLine -.IN "SmeLine object" "class name" -Superclass Sme -.De -.sp -.LP -The SmeLine object is used to add a horizontal line or menu separator to -a menu. Since each SmeLine is an independent object, the application -is able to change the color, height, and other attributes of the SmeLine -objects on an entry by entry basis. This object is not selectable, and -will not highlight when the pointer cursor is over it. -.NH 3 -Resources -.IN "SmeLine object" "resources" -.LP -The resources associated with the SmeLine object are defined in this section, -and affect only the single menu entry specified by this object. -.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 -destroyCallback Callback XtCallbackList NULL -foreground Foreground Pixel XtDefaultForeground -height Height Dimension \fBlineWidth\fP -international International Boolean C False -lineWidth LineWidth Dimension 1 -stipple Stipple Pixmap XtUnspecifiedPixmap -width Width Dimension 1 -.sp 3p -_ -.TE -.Dc -.IP \fBforeground\fP 1.5i -A pixel value which indexes the SimpleMenu's colormap to derive the -foreground color used to draw the separator line. -.Hw -Keep in mind that the SimpleMenu widget will force all menu items to -be the width of the widest entry. Thus, setting the width is generally not -very important. -.Ix -.IP \fBlineWidth\fP 1.5i -The width of the horizontal line that is to be displayed. -.IP \fBstipple\fP 1.5i -If a bitmap is specified for this resource, the line will be stippled -through it. This allows the menu separator to be rendered as something -more exciting than just a line. For instance, if you define a stipple -that is a chain link, then your menu separators will look like chains. diff --git a/xc/doc/specs/Xaw/StripChart b/xc/doc/specs/Xaw/StripChart deleted file mode 100644 index 7037a3838..000000000 --- a/xc/doc/specs/Xaw/StripChart +++ /dev/null @@ -1,160 +0,0 @@ -.\" $XConsortium: StripChart,v 1.22 94/05/01 19:21:00 gildea Exp $ -.NH 2 -StripChart Widget -.XS - StripChart Widget -.XE -.IN "StripChart widget" "" "@DEF@" -.Ds 0 -.TA 2.0i -.ta 2.0i -.sp -Application Header file <Xaw/StripChart.h> -.IN "StripChart.h" "" -Class Header file <Xaw/StripCharP.h> -.IN "StripCharP.h" "" -Class stripChartWidgetClass -.IN "stripChartWidgetClass" "" -Class Name StripChart -.IN "StripChart widget" "class name" -Superclass Simple -.sp -.De -.LP -The StripChart widget is used to provide a roughly real -time graphical chart of a single value. For example, -it is used by the common client program \fBxload\fP -to provide a graph of processor load. The StripChart -reads data from an application, and updates the chart -at the \fBupdate\fP interval specified. -.NH 3 -Resources -.LP -When creating a StripChart widget instance, the following resources are -retrieved from the argument list or from the resource database: -.LP -.IN "StripChart 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 -colormap Colormap Colormap Parent's Colormap -cursor Cursor Cursor None -cursorName Cursor String NULL -depth Depth int C Parent's Depth -destroyCallback Callback XtCallbackList NULL -foreground Foreground Pixel XtDefaultForeground -getValue Callback XtCallbackList NULL -height Height Dimension 120 -highlight Foreground Pixel XtDefaultForeground -insensitiveBorder Insensitive Pixmap GreyPixmap -international International Boolean C False -jumpScroll JumpScroll int A half the width of the widget -mappedWhenManaged MappedWhenManaged Boolean True -minScale Scale int 1 -pointerColor Foreground Pixel XtDefaultForeground -pointerColorBackground Background Pixel XtDefaultBackground -screen Screen Pointer R Parent's Screen -sensitive Sensitive Boolean True -translations Translations TranslationTable NULL -update Interval int 10 -width Width Dimension 120 -x Position Position 0 -y Position Position 0 -.sp 3p -_ -.TE -.Ac -.As -.Bg -.Gp -.Bc -.Bp -.Bw -.Cm -.Cu -.Cn -.Dp -.Dc -.IP \fBforeground\fP 1.5i -A pixel value which indexes the widget's colormap to derive the color -that will be used to draw the graph. -.IP \fBgetValue\fP 1.5i -A list of callback functions to call every \fBupdate\fP seconds. -This list should contain one function, which returns the -value to be graphed by the StripChart widget. The following -section describes the procedural interface. Behavior when this list has -more than one function is undefined. -.Hw -.IP \fBhighlight\fP 1.5i -A pixel value which indexes the widget's colormap to derive the color -that will be used to draw the scale lines on the graph. -.Ib -.Ix -.IP \fBjumpScroll\fP 1.5i -When the graph reaches the right edge of the window it must be -scrolled to the left. This resource specifies the number of pixels -it will jump. Smooth scrolling can be achieved by setting this resource -to 1. -.Mm -.IP \fBminScale\fP 1.5i -The minimum scale for the graph. The number of divisions on the graph -will always be greater than or equal to this value. -.Pf -.Pb -.Sc -.Se -.Tr -.IP \fBupdate\fP -The number of seconds between graph updates. Each update is -represented on the graph as a 1 pixel wide line. Every \fBupdate\fP seconds -the \fBgetValue\fP procedure will be used to get a new graph point, -and this point will be added to the right end of the StripChart. -.Xy -.NH 3 -Getting the StripChart Value -.IN "StripChart widget" "getting the value" -.LP -The StripChart widget will call the application routine passed to it -as the \fBgetValue\fP callback function every \fBupdate\fP seconds to -obtain another point for the StripChart graph. -.LP -The calling interface for the \fBgetValue\fP callback is: -.IN "StripChart widget" "getValue callback" "@DEF@" -.FD 0 -void (*\fIgetValueProc\fP)(\fIw\fP, \fIclient_data\fP, \fIvalue\fP) -.br - Widget \fIw\fP; -.br - XtPointer \fIclient_data\fP; -.br - XtPointer \fIvalue\fP; /* double * */ -.FN -.IP \fIw\fP 1i -Specifies the StripChart widget. -.IP \fIclient_data\fP 1i -Specifies the client data. -.IP \fIvalue\fP 1i -Returns a pointer to a double. The application should set the address -pointed to by this argument to a double containing the value to be -graphed on the StripChart. -.LP -This function is used by the StripChart to call an application routine. -The routine will pass the value to be graphed back to the the StripChart -in the \fBvalue\fP field of this routine. - diff --git a/xc/doc/specs/Xaw/TPage_Credits b/xc/doc/specs/Xaw/TPage_Credits deleted file mode 100644 index c8be8072d..000000000 --- a/xc/doc/specs/Xaw/TPage_Credits +++ /dev/null @@ -1,153 +0,0 @@ -.\" $TOG: TPage_Credits /main/21 1997/11/04 18:18:36 kaleb $ -.ds CH -.ds CF -.ps 11 -.nr PS 11 -\& -.sp 8 -.ce 5 -\s+2\fB\*(xW\fP\s-2 - -\s+1\fBX Window System\fP\s-1 - -\s+1\fBX Version 11, Release 6.4\fP\s-1 - -.sp 6 -.ce 4 -Chris D. Peterson -.sp 6p -formerly MIT X Consortium -.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, 1989, 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, 1989, 1991 -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 5 -.af PN i -.ds CF \fB\\n(PN\fP -.XS v -Acknowledgments -.XE -\& -.ce 3 -\s+1\fBAcknowledgments\fP\s-1 -.sp 2 -.na -.LP -Many thanks go to Ralph Swick (Project Athena / Digital) who has -contributed much time and effort to this widget set. Previous -versions of the widget set are largely due to his time and effort. -Many of the improvements that I have been able to make are because he -provided a solid foundation to build upon. While much of the effort -has been Ralph's, many other people have contributed to the code. -.LP -.Ds -Mark Ackerman (formerly Project Athena) -Donna Converse (MIT X Consortium) -Jim Fulton (formerly MIT X Consortium) -Loretta Guarino-Reid (Digital WSL) -Charles Haynes (Digital WSL) -Rich Hyde (Digital WSL) -Mary Larson (Digital UEG) -Joel McCormack (Digital WSL) -Ron Newman (formerly Project Athena) -Jeanne Rich (Digital WSL) -Terry Weissman (formerly Digital WSL) -.De -.LP -While not much remains of the X10 toolkit, many of the ideas for this -widget set come from that original version. The design and -implementation of the X10 toolkit were done by: -.LP -.Ds -Mike Gancarz (formerly Digital UEG) -Charles Haynes (Digital WSL) -Phil Karlton (formerly Digital WSL) -Kathleen Langone (Digital UEG) -Mary Larson (Digital UEG) -Ram Rao (Digital UEG) -Smokey Wallace (formerly Digital WSL) -Terry Weissman (formerly Digital WSL) -.De -.LP -I have used the formatting ideas, and some of the words from previous -versions of this document. The X11R3 Athena widget document was -written by: -.LP -.Ds -Ralph R. Swick (Project Athena/ Digital) -Terry Weissman (formerly Digital WSL) -Al Mento (Digital UEG) -.De -.LP -Putting this manual together was a major task in and of itself. I -would like to thank Ralph Swick, Donna Converse, and Jim Fulton for -taking the time to help convert my technical knowledge into legible -text. A special thanks to Jean Diaz (O'Reilly and Associates) for -spending nearly a month with me working out all the annoying little -details. -.sp -.Ds 0 -Chris D. Peterson -MIT X Consortium 1989 -.De -.LP -.sp -The R5 edition of this document has been edited by the research staff of -the MIT X Consortium, with significant contributions by Jim Fulton (NCD). -.sp -.Ds 0 -Donna Converse -MIT X Consortium 1991 -.De -.LP -.sp -The R6 edition of this document has been edited to reflect changes -brought about by research staff of the Omron Corporation, with special -recognition to Li Yuhong, Seiji Kuwari, and Hiroshi Kuribayashi for -the X11R5/contrib/lib/Xaw internationalization that inspired this version. -.sp -.Ds 0 -Frank Sheeran -Omron Corporation 1994 -.De diff --git a/xc/doc/specs/Xaw/Template b/xc/doc/specs/Xaw/Template deleted file mode 100644 index 7005e9096..000000000 --- a/xc/doc/specs/Xaw/Template +++ /dev/null @@ -1,426 +0,0 @@ -.\" $XConsortium: Template,v 1.14 94/05/01 19:21:03 gildea Exp $ -All Athena widgets have three separate files associated with them: -.LP -.IP \(bu 3 -A \*Qpublic\*U header file containing declarations needed by -applications programmers -.IP \(bu 3 -A \*Qprivate\*U header file containing additional declarations needed by the -widget and any subclasses -.IP \(bu 3 -A source code file containing the implementation of the widget -.LP -This separation of functions into three files is suggested for all -widgets, but nothing in the Toolkit actually requires this format. In -particular, a private widget created for a single application may easily -combine the \*Qpublic\*U and \*Qprivate\*U header files into a single file, or -merge the contents into another application header file. Similarly, the -widget implementation can be merged into other application code. -.LP -.sp -In the following example, the public header file -.Pn < X11/Xaw/Template.h >, -the private header file -.Pn < X11/Xaw/TemplateP.h > -and the source code file -.Pn < X11/Xaw/Template.c > -will be modified to produce the \*QWindowWidget\*U described above. -In each case, the files have been designed so that a global string -replacement of ``Template'' and ``template'' -with the name of your new widget, using -the appropriate case, can be done. -.NH 2 -Public Header File -.LP -The public header file contains declarations that will be required by any -application module that needs to refer to the widget; whether to create -an instance of the class, to perform an -.PN XtSetValues -operation, or to call a public routine implemented by the widget class. -.LP -The contents of the Template public header file, -.Pn < X11/Xaw/Template.h >, -are: -.de CB -.sp -.Ds 0 -.SM -.vs 10 -.in +.25i -.TA .25i 1.4i 2.4i 2.75i 3.5i -.ta .25i 1.4i 2.4i 2.75i 3.5i -.. -.de CE -.NL -.vs 13 -.De -.\".in -.25i -.. -.CB -.\".so ../../lib/Xaw/Template.h -/* XConsortium: Template.h,v 1.2 88/10/25 17:22:09 swick Exp $ */ -/* Copyright (c) X Consortium 1987, 1988 */ - -#ifndef _Template_h -#define _Template_h - -/**************************************************************** - * - * Template widget - * - ****************************************************************/ - -/* Resources: - - Name Class RepType Default Value - ---- ----- ------- ------------- - background Background Pixel XtDefaultBackground - border BorderColor Pixel XtDefaultForeground - borderWidth BorderWidth Dimension 1 - destroyCallback Callback Pointer NULL - height Height Dimension 0 - mappedWhenManaged MappedWhenManaged Boolean True - sensitive Sensitive Boolean True - width Width Dimension 0 - x Position Position 0 - y Position Position 0 - -*/ - -/* define any special resource names here that are not in <X11/StringDefs.h> */ - -#define XtNtemplateResource "templateResource" - -#define XtCTemplateResource "TemplateResource" - -/* declare specific TemplateWidget class and instance datatypes */ - -typedef struct _TemplateClassRec* TemplateWidgetClass; -typedef struct _TemplateRec* TemplateWidget; - -/* declare the class constant */ - -extern WidgetClass templateWidgetClass; - -#endif /* _Template_h */ -.CE -.LP -.sp -You will notice that most of this file is documentation. The crucial -parts are the last 8 lines where macros for any private resource names -and classes are defined and where the widget class datatypes and class -record pointer are declared. -.LP -For the \*QWindowWidget\*U, we want 2 drawing colors, a callback list for -user input and an -\fBexposeCallback\fP callback list, and we will declare three -convenience procedures, so we need to add -.LP -.sp -.CB -/* Resources: - ... - callback Callback Callback NULL - drawingColor1 Color Pixel XtDefaultForeground - drawingColor2 Color Pixel XtDefaultForeground - exposeCallback Callback Callback NULL - font Font XFontStruct* XtDefaultFont - ... - */ - -#define XtNdrawingColor1 "drawingColor1" -#define XtNdrawingColor2 "drawingColor2" -#define XtNexposeCallback "exposeCallback" - -extern Pixel WindowColor1(\|/* Widget */\|); -extern Pixel WindowColor2(\|/* Widget */\|); -extern Font\ \ WindowFont(\|/* Widget */\|); -.CE -.LP -Note that we have chosen to call the input callback list by the generic -name, \fBcallback\fP, rather than a specific name. If widgets that define -a single user-input action all choose the same resource name then there -is greater possibility for an application to switch between widgets of -different types. -.NH 2 -Private Header File -.LP -The private header file contains the complete declaration of the class -and instance structures for the widget and any additional private data -that will be required by anticipated subclasses of the widget. -Information in the private header file is normally hidden from the -application and is designed to be accessed only through other public -procedures; e.g. -.PN XtSetValues . -.LP -The contents of the Template private header file, -.Pn < X11/Xaw/TemplateP.h >, -are: -.CB -.\".so ../../lib/Xaw/TemplateP.h -/* XConsortium: TemplateP.h,v 1.2 88/10/25 17:31:47 swick Exp $ */ - -/* Copyright (c) X Consortium 1987, 1988 - */ - -#ifndef _TemplateP_h -#define _TemplateP_h - -#include <X11/Xaw/Template.h> -/* include superclass private header file */ -#include <X11/CoreP.h> - -/* define unique representation types not found in <X11/StringDefs.h> */ - -#define XtRTemplateResource "TemplateResource" - -typedef struct { - int empty; -} TemplateClassPart; - -typedef struct _TemplateClassRec { - CoreClassPart core_class; - TemplateClassPart template_class; -} TemplateClassRec; - -extern TemplateClassRec templateClassRec; - -typedef struct { - /* resources */ - char* resource; - /* private state */ -} TemplatePart; - -typedef struct _TemplateRec { - CorePart core; - TemplatePart template; -} TemplateRec; - -#endif /* _TemplateP_h */ -.CE -.LP -.sp -The private header file includes the private header file of its -superclass, thereby exposing the entire internal structure of the widget. -It may not always be advantageous to do this; your own project -development style will dictate the appropriate level of detail to expose -in each module. -.LP -The \*QWindowWidget\*U needs to declare two fields in its instance structure to -hold the drawing colors, a resource field for the font and a field for the -expose and user input callback lists: -.CB -typedef struct { - /* resources */ - Pixel color_1; - Pixel color_2; - XFontStruct* font; - XtCallbackList expose_callback; - XtCallbackList input_callback; - /* private state */ - /* (none) */ -} WindowPart; -.CE -.NH 2 -Widget Source File -.LP -The source code file implements the widget class itself. The unique -part of this file is the declaration and initialization of the -widget class record structure and the declaration of all resources and -action routines added by the widget class. -.LP -The contents of the Template implementation file, -.Pn < X11/Xaw/Template.c >, -are: -.CB -.\".so ../../lib/Xaw/Template.c -/* XConsortium: Template.c,v 1.2 88/10/25 17:40:25 swick Exp $ */ - -/* Copyright (c) X Consortium 1987, 1988 - */ - -#include <X11/IntrinsicP.h> -#include <X11/StringDefs.h> -#include "TemplateP.h" - -static XtResource resources[] = { -#define offset(field) XtOffsetOf(TemplateRec, template.field) - /* {name, class, type, size, offset, default_type, default_addr}, */ - { XtNtemplateResource, XtCTemplateResource, XtRTemplateResource, - sizeof(char*), offset(resource), XtRString, (XtPointer) "default" }, -#undef offset -}; - -static void TemplateAction(/* Widget, XEvent*, String*, Cardinal* */); - -static XtActionsRec actions[] = -{ - /* {name, procedure}, */ - {"template", TemplateAction}, -}; - -static char translations[] = -" <Key>: template(\|) \\n\\ -"; - -TemplateClassRec templateClassRec = { - { /* core fields */ - /* superclass */ (WidgetClass) &widgetClassRec, - /* class_name */ "Template", - /* widget_size */ sizeof(TemplateRec), - /* class_initialize */ NULL, - /* class_part_initialize */ NULL, - /* class_inited */ FALSE, - /* initialize */ NULL, - /* initialize_hook */ NULL, - /* realize */ XtInheritRealize, - /* actions */ actions, - /* num_actions */ XtNumber(actions), - /* resources */ resources, - /* num_resources */ XtNumber(resources), - /* xrm_class */ NULLQUARK, - /* compress_motion */ TRUE, - /* compress_exposure */ TRUE, - /* compress_enterleave */ TRUE, - /* visible_interest */ FALSE, - /* destroy */ NULL, - /* resize */ NULL, - /* expose */ NULL, - /* set_values */ NULL, - /* set_values_hook */ NULL, - /* set_values_almost */ XtInheritSetValuesAlmost, - /* get_values_hook */ NULL, - /* accept_focus */ NULL, - /* version */ XtVersion, - /* callback_private */ NULL, - /* tm_table */ translations, - /* query_geometry */ XtInheritQueryGeometry, - /* display_accelerator */ XtInheritDisplayAccelerator, - /* extension */ NULL - }, - { /* template fields */ - /* empty */ 0 - } -}; - -WidgetClass templateWidgetClass = (WidgetClass)&templateClassRec; - -.CE -The resource list for the \*QWindowWidget\*U might look like the following: -.CB -static XtResource resources[] = { -#define offset(field) XtOffsetOf(WindowWidgetRec, window.field) - /* {name, class, type, size, offset, default_type, default_addr}, */ - { XtNdrawingColor1, XtCColor, XtRPixel, sizeof(Pixel), - offset(color_1), XtRString, XtDefaultForeground }, - { XtNdrawingColor2, XtCColor, XtRPixel, sizeof(Pixel), - offset(color_2), XtRString, XtDefaultForeground }, - { XtNfont, XtCFont, XtRFontStruct, sizeof(XFontStruct*), - offset(font), XtRString, XtDefaultFont }, - { XtNexposeCallback, XtCCallback, XtRCallback, sizeof(XtCallbackList), - offset(expose_callback), XtRCallback, NULL }, - { XtNcallback, XtCCallback, XtRCallback, sizeof(XtCallbackList), - offset(input_callback), XtRCallback, NULL }, -#undef offset -}; -.CE -.LP -The user input callback will be implemented by an action procedure which -passes the event pointer as call_data. The action procedure -is declared as: -.CB -/* ARGSUSED */ -static void InputAction(w, event, params, num_params) - Widget w; - XEvent *event; - String *params; /* unused */ - Cardinal *num_params; /* unused */ -{ - XtCallCallbacks(w, XtNcallback, (XtPointer)event); -} - -static XtActionsRec actions[] = -{ - /* {name, procedure}, */ - {"input", InputAction}, -}; -.CE -.LP -and the default input binding will be to execute the input callbacks on -.PN KeyPress -and -.PN ButtonPress : -.LP -.CB -static char translations[] = -" <Key>: input(\|) \\n\\ - <BtnDown>: input(\|) \\ -"; -.CE -.LP -In the class record declaration and initialization, the only field that -is different from the Template is the expose procedure: -.CB -/* ARGSUSED */ -static void Redisplay(w, event, region) - Widget w; - XEvent *event; /* unused */ - Region region; -{ - XtCallCallbacks(w, XtNexposeCallback, (XtPointer)region); -} - -WindowClassRec windowClassRec = { - - ... - - /* expose */ Redisplay, -.CE -.LP -.sp -The \*QWindowWidget\*U will also declare three public procedures to return the -drawing colors and the font id, saving the application the effort of -constructing an argument list for a call to -.PN XtGetValues : -.LP -.CB -Pixel WindowColor1(w) - Widget w; -{ - return ((WindowWidget)w)->window.color_1; -} - -Pixel WindowColor2(w) - Widget w; -{ - return ((WindowWidget)w)->window.color_2; -} - -Font WindowFont(w) - Widget w; -{ - return ((WindowWidget)w)->window.font->fid; -} -.CE -.LP -The \*QWindowWidget\*U is now complete. The application can retrieve the two -drawing colors from the widget instance by calling either -.PN XtGetValues , -or the \fBWindowColor\fP functions. The actual window created for the -\*QWindowWidget\*U is available by calling the -.PN XtWindow -function. -.ds LH -.ds CH -.ds RH -.nr PN +1 -.XS -Index -.XE -.tm .pn \n(PN -.nr PN -1 -.\" print Table of Contents -.if o .bp \" blank page to make count even -.bp 3 -.af PN i -.PX diff --git a/xc/doc/specs/Xaw/Text b/xc/doc/specs/Xaw/Text deleted file mode 100644 index 0bc4f2750..000000000 --- a/xc/doc/specs/Xaw/Text +++ /dev/null @@ -1,123 +0,0 @@ -.\" $XConsortium: Text,v 1.19 94/05/01 19:21:06 gildea Exp $ -.NH 2 -Text Widget -.LP -.XS - Text Widget -.XE -.IN "Text widget" "" "@DEF@" -.LP -.Ds 0 -.TA 2.0i -.ta 2.0i -Application Header file <X11/Xaw/Text.h> -.IN "Text.h" "" -Class Header file <X11/Xaw/TextP.h> -.IN "TextP.h" "" -Class textWidgetClass -.IN "textWidgetClass" "" -Class Name Text -.IN "Text widget" "class name" -Superclass Simple -.De -.sp 1 -.LP -The Text widget is the glue that binds all the other pieces together, it -maintains the internal state of the displayed text, and acts as a -mediator between the source and sink. -.LP -This section lists the resources that are actually part of the -Text widget, and explains the functionality provided by each. -.NH 3 -Resources -.LP -When creating an Text widget instance, the following resources are -retrieved from the argument list or from the resource database: -.LP -.IN "Text 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 -colormap Colormap Colormap Parent's Colormap -cursor Cursor Cursor XC_xterm -cursorName Cursor String NULL -depth Depth int C Parent's Depth -destroyCallback Callback XtCallbackList NULL -displayCaret Output Boolean True -displayPosition TextPosition XawTextPosition 0 -height Height Dimension A Font height + margins -insensitiveBorder Insensitive Pixmap GreyPixmap -insertPosition TextPosition int 0 -leftMargin Margin Position 2 -mappedWhenManaged MappedWhenManaged Boolean True -pointerColor Foreground Pixel XtDefaultForeground -pointerColorBackground Background Pixel XtDefaultBackground -resize Resize XawTextResizeMode XawtextResizeNever -rightMargin Margin Position 4 -screen Screen Pointer R Parent's Screen -scrollHorizontal Scroll ScrollMode XawtextScrollNever -scrollVertical Scroll XawTextScrollMode XawtextScrollNever -selectTypes SelectTypes XawTextSelectType* See above -sensitive Sensitive Boolean True -textSink TextSink Widget NULL -textSource TextSource Widget NULL -topMargin Margin Position 2 -translations Translations TranslationTable See above -unrealizeCallback Callback XtCallbackList NULL -width Width Dimension 100 -wrap Wrap WrapMode XawtextWrapNever -x Position Position 0 -y Position Position 0 -.sp 3p -_ -.TE -.Ac -.As -.Af Bold -.Bg -.Gp -.Bc -.Bp -.Bw -.Tm Bold -.Cm -.Cu -.Cn -.Dp -.Dc -.Tc Bold -.Td Bold -.Hw -.Ib -.Ti Bold -.Mm -.Pf -.Pb -.Tz Bold -.Sc -.Ts Bold -.St Bold -.Se -.To Bold -.Tr -.Tw Bold -.Tu Bold -.Xy diff --git a/xc/doc/specs/Xaw/TextActions b/xc/doc/specs/Xaw/TextActions deleted file mode 100644 index 28263d92b..000000000 --- a/xc/doc/specs/Xaw/TextActions +++ /dev/null @@ -1,506 +0,0 @@ -.\" $XConsortium: TextActions,v 1.20 94/05/01 20:15:31 gildea Exp $ -.NH 2 -Text Widget Actions -.LP -.IN "Text widget" "actions" -.XS - Actions Supported by all Text Widgets -.XE -.IN "Text widget" "actions" "@DEF@" - -All editing functions are performed by translation manager actions that may -be specified through the \fBtranslations\fP resource in the Text widget. -.LP -.sp -.Ds 0 -.TA .5i 2.5i 3i -.ta .5i 2.5i 3i -Insert Point Movement Delete - forward-character delete-next-character - backward-character delete-previous-character - forward-word delete-next-word - backward-word delete-previous-word - forward-paragraph delete-selection - backward-paragraph - beginning-of-line - end-of-line Selection - next-line select-word - previous-line select-all - next-page select-start - previous-page select-adjust - beginning-of-file select-end - end-of-file extend-start - scroll-one-line-up extend-adjust - scroll-one-line-down extend-end - insert-selection - - -Miscellaneous New Line - redraw-display newline-and-indent - insert-file newline-and-backup - insert-char newline - insert-string - display-caret - focus-in Kill - focus-in kill-word - search backward-kill-word - multiply kill-selection - form-paragraph kill-to-end-of-line - transpose-characters kill-paragraph - no-op kill-to-end-of-paragraph - XawWMProtocols - reconnect-im -.De -.sp -.LP -Most of the actions take no arguments, and unless otherwise noted you -may assume this to be the case. -.LP -.NH 3 -Cursor Movement Actions\fP -.LP -.sp -.IP forward-character(\|) 2.0i -.br -.ns -.IP backward-character(\|) 2.0i -These actions move the insert point forward or backward one character in -the buffer. If the insert point is at the end or beginning of a line -this action will move the insert point to the next (or previous) line. -.IP forward-word(\|) 2.0i -.br -.ns -.IP backward-word(\|) 2.0i -These actions move the insert point to the next or previous word boundary. -A word boundary is defined as a Space, Tab or Carriage Return. -.IP forward-paragraph(\|) 2.0i -.br -.ns -.IP backward-paragraph(\|) 2.0i -These actions move the insert point to the next or previous paragraph boundary. -A paragraph boundary is defined as two Carriage Returns in a row with only -Spaces or Tabs between them. -.IP beginning-of-line(\|) 2.0i -.br -.ns -.IP end-of-line(\|) 2.0i -These actions move to the beginning or end of the current line. If the -insert point is already at the end or beginning of the line then no action is taken. -.IP next-line(\|) 2.0i -.br -.ns -.IP previous-line(\|) 2.0i -These actions move the insert point up or down one line. If the insert -point is currently N characters from the beginning of the line then it -will be N characters from the beginning of the next or previous line. -If N is past the end of the line, the insert point is placed at the end -of the line. -.IP next-page(\|) 2.0i -.br -.ns -.IP previous-page(\|) 2.0i -These actions move the insert point up or down one page in the file. -One page is defined as the current height of the text widget. The -insert point is always placed at the first character of the top line by -this action. -.IP beginning-of-file(\|) 2.0i -.br -.ns -.IP end-of-file(\|) 2.0i -These actions place the insert point at the beginning or end of the -current text buffer. The text widget is then scrolled the minimum -amount necessary to make the new insert point location visible. -.IP scroll-one-line-up(\|) 2.0i -.br -.ns -.IP scroll-one-line-down(\|) 2.0i -These actions scroll the current text field up or down by one line. -They do not move the insert point. Other than the scrollbars this is -the only way that the insert point may be moved off of the visible text -area. The widget will be scrolled so that the insert point is back on -the screen as soon as some other action is executed. -.NH 3 -Delete Actions -.LP -.sp -.IP delete-next-character(\|) 2.0i -.br -.ns -.IP delete-previous-character(\|) 2.0i -These actions remove the character immediately before or after the -insert point. If a Carriage Return is removed then the next line is -appended to the end of the current line. -.IP delete-next-word(\|) 2.0i -.br -.ns -.IP delete-previous-word(\|) 2.0i -These actions remove all characters between the insert point location and -the next word boundary. A word boundary is defined as a Space, Tab or -Carriage Return. -.IP delete-selection(\|) 2.0i -This action removes all characters in the current selection. -The selection can be set with the selection actions. -.NH 3 -Selection Actions -.LP -.sp -.IP select-word(\|) 2.0i -This action selects the word in which the insert point is currently located. -If the insert point is between words then it will select the previous word. -.IP select-all(\|) 2.0i -This action selects the entire text buffer. -.IP select-start(\|) 2.0i -This action sets the insert point to the current pointer location (if -triggered by a button event) or text cursor location (if triggered by -a key event). It -will then begin a selection at this location. If many of these -selection actions occur quickly in succession then the selection count -mechanism will be invoked (see the section titled \fBText Selections for -Application Programmers\fP for details). -.IP select-adjust(\|) 2.0i -This action allows a selection started with the \fIselect-start\fP -action to be modified, as described above. -.IP select-end(\fIname\fP[,\fIname\fP,...]) 2.0i -This action ends a text selection that began with the \fIselect-start\fP -action, and asserts ownership of the selection or selections specified. -A \fIname\fP can be a selection (e.g., \fBPRIMARY\fP) or a cut buffer -(e.g., \fBCUT_BUFFER0\fP). Note that case is important. If no -\fInames\fP are specified, \fBPRIMARY\fP is asserted. -.IP extend-start(\|) 2.0i -This action finds the nearest end of the current selection, and moves it -to the current pointer location (if triggered by a button event) or text -cursor location (if triggered by a key event). -.IP extend-adjust(\|) 2.0i -This action allows a selection started with an \fIextend-start\fP action -to be modified. -.IP extend-end(\fIname\fP[,\fIname\fP,...]) 2.0i -This action ends a text selection that began with the \fIextend-start\fP -action, and asserts ownership of the selection or selections specified. -A \fIname\fP can be a selection (e.g. \fBPRIMARY\fP) or a cut buffer -(e.g \fBCUT_BUFFER0\fP). Note that case is important. If no names are -given, \fBPRIMARY\fP is asserted. -.IP insert-selection(\fIname\fP[,\fIname\fP,...]) 2.0i -This action retrieves the value of the first (left-most) named selection -that exists or the cut buffer that is not empty and inserts it into the -Text widget at the current insert point location. A \fIname\fP can be a -selection (e.g. \fBPRIMARY\fP) or a cut buffer (e.g \fBCUT_BUFFER0\fP). -Note that case is important. -.NH 3 -The New Line Actions -.LP -.sp -.IP newline-and-indent(\|) 2.0i -This action inserts a newline into the text and adds spaces to -that line to indent it to match the previous line. -.IP newline-and-backup(\|) 2.0i -This action inserts a newline into the text \fIafter\fP the insert point. -.IP newline(\|) 2.0i -This action inserts a newline into the text \fIbefore\fP the insert point. -.NH 3 -Kill and Actions -.LP -.sp -.IP kill-word(\|) 2.0i -.br -.ns -.IP backward-kill-word(\|) 2.0i -These actions act exactly like the \fIdelete-next-word\fP and -\fIdelete-previous-word\fP actions, but they stuff the word that was -killed into the kill buffer (\fBCUT_BUFFER_1\fP). -.IP kill-selection(\|) 2.0i -This action deletes the current selection and stuffs the deleted text into -the kill buffer (\fBCUT_BUFFER_1\fP). -.IP kill-to-end-of-line(\|) 2.0i -This action deletes the entire line to the right of the insert point position, -and stuffs the deleted text into the kill buffer (\fBCUT_BUFFER_1\fP). -.IP kill-paragraph(\|) 2.0i -This action deletes the current paragraph, if between paragraphs it deletes -the paragraph above the insert point, and stuffs the deleted text into -the kill buffer (\fBCUT_BUFFER_1\fP). -.IP kill-to-end-of-paragraph(\|) 2.0i -This action deletes everything between the current insert point location and -the next paragraph boundary, and stuffs the deleted text into the kill -buffer (\fBCUT_BUFFER_1\fP). -.NH 3 -Miscellaneous Actions -.LP -.sp 1 -.IP redraw-display(\|) 2.0i -This action recomputes the location of all the text lines on the -display, scrolls the text to vertically center the line containing the insert point -on the screen, clears the entire screen, and redisplays it. -.IP insert-file([\fIfilename\fP]) 2.0i -This action activates the insert file popup. The \fIfilename\fP -option specifies the default filename to put in the filename buffer of -the popup. If no \fIfilename\fP is specified the buffer is empty -at startup. -.IP insert-char(\|) 2.0i -This action may only be attached to a key event. When the -\fBinternational\fP resource is \fBfalse\fP, this action -calls XLookupString to translate the event into a (rebindable) Latin-1 -character (sequence) and inserts it into the text at the -insert point. When the \fBinternational\fP resource is \fBtrue\fP, -characters are passed to the input method via XwcLookupString, and any -committed string returned is inserted into the text at the insert point. -.IP insert-string(\fIstring\fP[,\fIstring\fP,...]) 2.0i -This action inserts each \fIstring\fP into the text -at the insert point location. Any \fIstring\fP -beginning with the characters "0x" followed by an even -number of hexadecimal digits is -interpreted as a hexadecimal constant and the -corresponding string is inserted instead. This -hexadecimal string may represent up to 50 8-bit characters. - When the\fBinternational\fP resource is -\fBtrue\fP, a hexadecimal string is intrepeted as -being in a multi-byte encoding, and a hexadecimal -or regular string will result in an error message -if it is not legal in the current locale. -.IP display-caret(\fIstate\fP,\fIwhen\fP) 2.0i -This action allows the insert point to be turned on and off. -The \fIstate\fP argument specifies the desired state of the insert point. -This value may be any of the string -values accepted for Boolean resources (e.g. \fBon\fP, \fBTrue\fP, -\fBoff\fP, \fBFalse\fP, etc.). If no arguments are specified, the -default value is \fBTrue\fP. -The \fIwhen\fP argument specifies, for \fBEnterNotify\fP or \fBLeaveNotify\fP -events whether or not the focus field in the event is to be examined. -If the second argument is not specified, or specified as something other -than \fBalways\fP then if the action is bound to an \fBEnterNotify\fP -or \fBLeaveNotify\fP event, the action will be taken only if the focus -field is \fBTrue\fP. An augmented binding that might be useful is: -.LP -.Ds 0 -.TA 2.0i 2.5i 4.0i -.ta 2.0i 2.5i 4.0i - *Text.Translations: #override \\ - <FocusIn>: display-caret(on) \\n\\ - <FocusOut>: display-caret(off) -.De -.IP focus-in(\|) 2.0i -.br -.ns -.IP focus-out(\|) 2.0i -These actions do not currently do anything. -.IP search(\fIdirection\fP,[\fIstring\fP]) 2.0i -This action activates the search popup. The \fIdirection\fP must be -specified as either \fBforward\fP or \fBbackward\fP. The string is -optional and is used as an initial value for the \fISearch for\fP: string. -For further explanation of the search widget see the section on -\fBText Searches\fP. -.IP multiply(\fIvalue\fP) 2.0i -The multiply action allows the user to multiply the effects of many of -the text actions. Thus the following action sequence -\fImultiply(10) delete-next-word()\fP will delete 10 words. It does not -matter whether these actions take place in one event or many events. -Using the default translations the key sequence \fIControl-u, -Control-d\fP will delete 4 characters. -Multiply actions can be chained, thus \fImultiply(5) -multiply(5)\fP is the same as \fImultiply(25)\fP. If the string -\fBreset\fP is passed to the multiply action the effects of all previous -multiplies are removed and a beep is sent to the display. -.IP form-paragraph(\|) 2.0i -This action removes all the Carriage Returns from the current -paragraph and reinserts them so that each line is as long as possible, while -still fitting on the current screen. Lines are broken at word boundaries if -at all possible. This action currently works only on Text widgets -that use ASCII text. -.IP transpose-characters(\|) 2.0i -This action will swap the position of the character to the left of the -insert point with the character to the right of the insert point. The insert point will then -be advanced one character. -.IP no-op([\fIaction\fP]) 2.0i -The no-op action makes no change to the text widget, and is mainly used -to override translations. This action takes one optional argument. If -this argument is \fIRingBell\fP then a beep is sent to the display. -.IP XawWMProtocols([\fIwm_protocol_name\fP]) 2.0i -.IN "XawWMProtocols" -.sp -This action is written specifically for the file insertion and the search -and replace -dialog boxes. This action is attached to those shells by the Text widget, -in order to handle ClientMessage events with the WM_PROTOCOLS atom in the -detail field. This action supports WM_DELETE_WINDOW on the Text widget -popups, and may support other window manager protocols if necessary in -the future. The popup will be dismissed if the window manager sends -a WM_DELETE_WINDOW request and there are no parameters in the action -call, which is the default. The popup will also be dismissed if the -parameters include the string ``wm_delete_window,'' and the event is a -ClientMessage event requesting dismissal or is not a ClientMessage event. -This action is not sensitive to the case of the strings passed as parameters. -.IP reconnect-im() 2.0i -.IN "Input Method" -When the \fBinternational\fP resource is \fBtrue\fP, -input is usually passed to an input method, a separate -process, for composing. Sometimes the connection to -this process gets severed; this action will attempt to -reconnect it. Causes for severage include network -trouble, and the user explicitly killing one input -method and starting a new one. This action may also -establish first connection when the application is -started before the input method. -.NH 3 -Text Selections for Application Programmers -.IN "Text widget" "Text Selections for Application Programmers" -.LP -The default behavior of the text selection array is described in the -section called \fBText Selections for Users\fP. To modify the selections -a programmer must construct a \fBXawTextSelectType\fP array (called the -selection array), containing the selections desired, and pass this as -the new value for the \fBselectionTypes\fP resource. The selection -array may also be modified using the \fBXawTextSetSelectionArray\fP -.IN "XawTextSetSelectionArray" "" -function. All selection arrays must end with the value -\fBXawselectNull\fP. The \fBselectionTypes\fP resource has no converter -registered and cannot be modified through the resource manager. -.LP -The array contains a list of entries that will be called when the user -attempts to select text in rapid succession with the \fIselect-start\fP -action (usually by clicking a pointer button). The first entry in the -selection array will be used when the \fIselect-start\fP action is -initially called. The next entry will be used when \fIselect-start\fP -is called again, and so on. If a timeout value (1/10 of a second) is -exceeded, the the next \fIselect-start\fP action will begin at the top -of the selection array. When \fBXawselectNull\fP is reached the array -is recycled beginning with the first element. -.TS -lw(1.25i) lw(4.25i). -T{ -\fBXawselectAll\fP -.IN "XawselectAll" "" -T} T{ -Selects the contents of the entire buffer. -T} -.sp 6p -T{ -\fBXawselectChar\fP -.IN "XawselectChar" "" -T} T{ -Selects text characters as the pointer moves over them. -T} -.sp 6p -T{ -\fBXawselectLine\fP -.IN "XawselectLine" "" -T} T{ -Selects the entire line. -T} -.sp 6p -T{ -\fBXawselectNull\fP -.IN "XawselectNull" "" -T} T{ -Indicates the end of the selection array. -T} -.sp 6p -T{ -\fBXawselectParagraph\fP -.IN "XawselectParagraph" "" -T} T{ -Selects the entire paragraph. -T} -.sp 6p -T{ -\fBXawselectPosition\fP -.IN "XawselectPosition" "" -T} T{ -Selects the current pointer position. -T} -.sp 6p -T{ -\fBXawselectWord\fP -.IN "XawselectWord" "" -T} T{ -Selects whole words as the pointer moves onto them. -T} -.TE -.LP -The default selectType array is: -.LP -.sp -.Ds 0 -{XawselectPosition, XawselectWord, XawselectLine, XawselectParagraph, XawselectAll, XawselectNull} -.De -.sp -.LP -The selection array is not copied by the text widgets. The -application must allocate space for the array and cannot deallocate or -change it until the text widget is destroyed or until a new selection -array is set. -.NH 2 -Default Translation Bindings -.LP -.XS - Default Translation Bindings -.XE -.IN "Text widget" "default translations" -The following translations are defaults built into every Text widget. -They can be overridden, or replaced by specifying a new value for the -Text widget's \fBtranslations\fP resource. -.LP -.sp -.Ds 0 -.TA .5i 2.5i -.ta .5i 2.5i - Ctrl<Key>A: beginning-of-line(\|) \\n\\ - Ctrl<Key>B: backward-character(\|) \\n\\ - Ctrl<Key>D: delete-next-character(\|) \\n\\ - Ctrl<Key>E: end-of-line(\|) \\n\\ - Ctrl<Key>F: forward-character(\|) \\n\\ - Ctrl<Key>G: multiply(Reset) \\n\\ - Ctrl<Key>H: delete-previous-character(\|) \\n\\ - Ctrl<Key>J: newline-and-indent(\|) \\n\\ - Ctrl<Key>K: kill-to-end-of-line(\|) \\n\\ - Ctrl<Key>L: redraw-display(\|) \\n\\ - Ctrl<Key>M: newline(\|) \\n\\ - Ctrl<Key>N: next-line(\|) \\n\\ - Ctrl<Key>O: newline-and-backup(\|) \\n\\ - Ctrl<Key>P: previous-line(\|) \\n\\ - Ctrl<Key>R: search(backward) \\n\\ - Ctrl<Key>S: search(forward) \\n\\ - Ctrl<Key>T: transpose-characters(\|) \\n\\ - Ctrl<Key>U: multiply(4) \\n\\ - Ctrl<Key>V: next-page(\|) \\n\\ - Ctrl<Key>W: kill-selection(\|) \\n\\ - Ctrl<Key>Y: insert-selection(CUT_BUFFER1) \\n\\ - Ctrl<Key>Z: scroll-one-line-up(\|) \\n\\ - Ctrl<Key>\\: reconnect-im(\|) \\n\\ - Meta<Key>B: backward-word(\|) \\n\\ - Meta<Key>F: forward-word(\|) \\n\\ - Meta<Key>I: insert-file(\|) \\n\\ - Meta<Key>K: kill-to-end-of-paragraph(\|) \\n\\ - Meta<Key>Q: form-paragraph(\|) \\n\\ - Meta<Key>V: previous-page(\|) \\n\\ - Meta<Key>Y: insert-selection(PRIMARY, CUT_BUFFER0) \\n\\ - Meta<Key>Z: scroll-one-line-down(\|) \\n\\ - :Meta<Key>d: delete-next-word(\|) \\n\\ - :Meta<Key>D: kill-word(\|) \\n\\ - :Meta<Key>h: delete-previous-word(\|) \\n\\ - :Meta<Key>H: backward-kill-word(\|) \\n\\ - :Meta<Key>\\<: beginning-of-file(\|) \\n\\ - :Meta<Key>\\>: end-of-file(\|) \\n\\ - :Meta<Key>]: forward-paragraph(\|) \\n\\ - :Meta<Key>[: backward-paragraph(\|) \\n\\ - ~Shift Meta<Key>Delete: delete-previous-word(\|) \\n\\ - \ Shift Meta<Key>Delete: backward-kill-word(\|) \\n\\ - ~Shift Meta<Key>Backspace: delete-previous-word(\|) \\n\\ - \ Shift Meta<Key>Backspace: backward-kill-word(\|) \\n\\ - <Key>Right: forward-character(\|) \\n\\ - <Key>Left: backward-character(\|) \\n\\ - <Key>Down: next-line(\|) \\n\\ - <Key>Up: previous-line(\|) \\n\\ - <Key>Delete: delete-previous-character(\|) \\n\\ - <Key>BackSpace: delete-previous-character(\|) \\n\\ - <Key>Linefeed: newline-and-indent(\|) \\n\\ - <Key>Return: newline(\|) \\n\\ - <Key>: insert-char(\|) \\n\\ - <Key>Kanji: reconnect-im(\|) \\n\\ - <FocusIn>: focus-in(\|) \\n\\ - <FocusOut>: focus-out(\|) \\n\\ - <Btn1Down>: select-start(\|) \\n\\ - <Btn1Motion>: extend-adjust(\|) \\n\\ - <Btn1Up>: extend-end(PRIMARY, CUT_BUFFER0) \\n\\ - <Btn2Down>: insert-selection(PRIMARY, CUT_BUFFER0) \\n\\ - <Btn3Down>: extend-start(\|) \\n\\ - <Btn3Motion>: extend-adjust(\|) \\n\\ - <Btn3Up>: extend-end(PRIMARY, CUT_BUFFER0) \\n -.De diff --git a/xc/doc/specs/Xaw/TextCustom b/xc/doc/specs/Xaw/TextCustom deleted file mode 100644 index 0c8039280..000000000 --- a/xc/doc/specs/Xaw/TextCustom +++ /dev/null @@ -1,63 +0,0 @@ -.NH 2 -Customizing the Text Widget -.LP -.XS - Customizing the Text Widget -.XE -.IN "Text widget" "customizing" "@DEF@" -.LP -The remainder of this chapter will describe customizing the Text -widget. The Text widget may be customized by subclassing, or by -creating new sources and sinks. Subclassing is described in -detail in Chapter 7; this section will describe only those things that -are specific to the Text widget. Attributes of the Text widget base -class and creating new sources and sinks will be discussed. -.LP -The Text widget is made up of a number of different pieces, with the -Text widget as the base widget class. It and the AsciiText widget are -the only true "widgets" in the Text widget family. The other pieces -(sources and sinks) are X Toolkit objects and have no window -associated with them. No source or sink is useful unless assigned to -a Text widget. -.LP -Each of the following pieces of the Text widget has a specific purpose, -and will be, or has been, discussed in detail in this chapter: -.IN "Text widget" "" -.IP \fBText\fP 15 -This is the glue that binds everything else together. This widget reads -the text data from the source, and displays the information in the sink. -All translations and actions are handled in the Text widget itself. -.IN "TextSink object" "" -.IP \fBTextSink\fP 15 -This object is responsible for displaying and clearing the drawing area. -It also reports the configuration of the window that contains the -drawing area. The TextSink does not have its own window; instead it does -its drawing on the Text widget's window. -.IN "TextSrc object" "" -.IP \fBTextSrc\fP 15 -This object is responsible for reading, editing and searching through the -text buffer. -.IN "AsciiSink object" "" -.IP \fBAsciiSink\fP 15 -This object is a subclass of the TextSink and knows how to display -ASCII text. Support has been added to display any 8-bit character set, given -the font. -.IN "MultiSink object" "" -.IP \fBMultiSink\fP 15 -This object is a subclass of the TextSink and knows how to display -font sets. -.IN "AsciiSrc object" "" -.IP \fBAsciiSrc\fP 15 -This object is a subclass of the TextSrc and knows how to read strings -and files. -.IN "MultiSrc object" "" -.IP \fBMultiSrc\fP 15 -This object is a subclass of the TextSrc and knows how to read strings -and multibyte files, converting them to wide characters based on locale. -.IN "AsciiText widget" "" -.IP \fBAsciiText\fP 15 -This widget is a subclass of the Text widget. When created, the AsciiText -automatically creates and attaches either an AsciiSrc and AsciiSink, or a -MultiSrc and MultiSink, to itself. The AsciiText provides the simplest -interface to the Athena Text widgets. - diff --git a/xc/doc/specs/Xaw/TextFuncs b/xc/doc/specs/Xaw/TextFuncs deleted file mode 100644 index dd4b27ce2..000000000 --- a/xc/doc/specs/Xaw/TextFuncs +++ /dev/null @@ -1,397 +0,0 @@ -.\" $XConsortium: TextFuncs,v 1.13 94/05/01 19:24:33 gildea Exp $ -.NH 2 -Text Functions -.XS - Text Functions -.XE -.LP -The following functions are provided as convenience routines for use with -the Text widget. Although many of these actions can be performed by -modifying resources, these interfaces are frequently more efficient. -.LP -These data structures are defined in the Text widget's public header file, -<X11/Xaw/Text.h>. -.LP -.IN "XawTextPosition" "" "@DEF@" -typedef long XawTextPosition; -.sp -.LP -Character positions in the Text widget begin at 0 and end at n, where -n is the number of characters in the Text source widget. -.LP -.IN "XawTextBlock" "" "@DEF@" -.Ds 0 -.TA .5i 1.5i 2.25i -.ta .5i 1.5i 2.25i -typedef struct { - int \fIfirstPos\fP; - int \fIlength\fP; - char *\fIptr\fP; - unsigned long \fIformat\fP; -} XawTextBlock, *XawTextBlockPtr; -.De -.LP -.IN "XawTextBlockPtr" "" -.IP \fIfirstPos\fP 1.0i -The first position, or index, to use within the \fIptr\fP field. -The value is commonly zero. -.IP \fIlength\fP 1.0i -The number of characters to be used from the \fIptr\fP field. -The number of characters used is commonly the number of characters -in \fIptr\fP, and must not be greater than the length of the string -in \fIptr\fP. -.IP \fIptr\fP 1.0i -Contains the string to be referenced by the Text widget. -.IP \fIformat\fP 1.0i -This flag indicates whether the data pointed to by \fBptr\fP is char -or wchar_t. When the associated widget has \fBinternational\fP set -to \fBfalse\fP this field must be XawFmt8Bit. When the associated -widget has \fBinternational\fP set to \fBtrue\fP this field must be -either XawFmt8Bit or XawFmtWide. -.LP -Note: Previous versions of Xaw used -.PN FMT8BIT , -which has been retained for backwards compatibility. \fBFMT8BIT\fP is -deprecated and will eventually be removed from the implementation. -.NH 3 -Selecting Text -.LP -To select a piece of text, use -.PN XawTextSetSelection : -.IN "XawTextSetSelection" "" "@DEF@" -.FD 0 -void XawTextSetSelection(\fIw\fP, \fIleft\fP, \fIright\fP) -.br - Widget \fIw\fP; -.br - XawTextPosition \fIleft\fP, \fIright\fP; -.FN -.IP \fIw\fP 1i -Specifies the Text widget. -.IP \fIleft\fP 1i -Specifies the character position at which the selection begins. -.IP \fIright\fP 1i -Specifies the character position at which the selection ends. -.LP -See section 5.4 for a description of \fBXawTextPosition\fP. -If redisplay is enabled, this function highlights the text and -makes it the \fBPRIMARY\fP selection. This function does not have any -effect on \fBCUT_BUFFER0\fP. -.LP -.NH 3 -Unhighlighting Text -.LP -To unhighlight previously highlighted text in a widget, use -\fBXawTextUnsetSelection\fP: -.IN "XawTextUnsetSelection" "" "@DEF@" -.FD 0 -void XawTextUnsetSelection(\fIw\fP) -.br - Widget \fIw\fP; -.FN -.IP \fIw\fP 1i -Specifies the Text widget. -.NH 3 -Getting Current Text Selection -.LP -To retrieve the text that has been selected by this -text widget use \fBXawTextGetSelectionPos\fP: -.IN "XawTextGetSelectionPos" "" "@DEF@" -.FD 0 -void XawTextGetSelectionPos(\fIw\fP, \fIbegin_return\fP, \fIend_return\fP) -.br - Widget \fIw\fP; -.br - XawTextPosition *\fIbegin_return\fP, *\fIend_return\fP; -.FN -.IP \fIw\fP 1i -Specifies the Text widget. -.IP \fIbegin_return\fP 1i -Returns the beginning of the text selection. -.IP \fIend_return\fP 1i -Returns the end of the text selection. -.LP -See section 5.4 for a description of \fBXawTextPosition\fP. -If the returned values are equal, no text is currently selected. -.NH 3 -Replacing Text -.LP -To modify the text in an editable Text widget use \fBXawTextReplace\fP: -.IN "XawTextReplace" "" "@DEF@" -.FD 0 -int XawTextReplace(\fIw\fP, \fIstart\fP, \fIend\fP, \fItext\fP) -.br - Widget \fIw\fP; -.br - XawTextPosition \fIstart\fP, \fIend\fP; -.br - XawTextBlock *\fItext\fP; -.FN -.IP \fIw\fP 1i -Specifies the Text widget. -.IP \fIstart\fP 1i -Specifies the starting character position of the text replacement. -.IP \fIend\fP 1i -Specifies the ending character position of the text replacement. -.IP \fItext\fP 1i -Specifies the text to be inserted into the file. -.LP -This function will not -be able to replace text in read-only text widgets. It will also only -be able to append text to an append-only text widget. -.LP -See section 5.4 for a description of \fBXawTextPosition\fP and -\fBXawTextBlock\fP. -.LP -This function may return the following values: -.IP \fBXawEditDone\fP 1.25i -.IN "XawEditDone" "" -The text replacement was successful. -.IP \fBXawPositionError\fP 1.25i -.IN "XawPositionError" "" -The edit mode is \fBXawtextAppend\fP and \fIstart\fP is not the position of -the last character of the source. -.IP \fBXawEditError\fP 1.25i -.IN "XawEditError" "" -Either the Source was read-only or the range to be deleted is larger -than the length of the Source. - -.LP -The \fBXawTextReplace\fP arguments \fIstart\fP and -\fIend\fP represent the text source character positions for the -existing text that is to be replaced by the text in the text block. -The characters from \fIstart\fP up to -but not including \fIend\fP are deleted, and the characters -specified on the text block are inserted in their place. If -\fIstart\fP and \fIend\fP are equal, no text is deleted and the new -text is inserted after \fIstart\fP. -.NH 3 -Searching for Text -.LP -To search for a string in the Text widget, use -\fBXawTextSearch\fP: -.IN "XawTextSearch" "" "@DEF@" -.FD 0 -XawTextPosition XawTextSearch(\fIw\fP, \fIdir\fP, \fItext\fP) -.br - Widget \fIw\fP; -.br - XawTextScanDirection \fIdir\fP; -.br - XawTextBlock * \fItext\fP; -.FN -.IP \fIw\fP 1i -Specifies the Text widget. -.IP \fIdir\fP 1i -Specifies the direction to search in. Legal values are -\fBXawsdLeft\fP and \fBXawsdRight\fP. -.IP \fItext\fP 1i -Specifies a text block structure that contains the text to search for. -.LP -See section 5.4 for a description of \fBXawTextPosition\fP and \fBXawTextBlock\fP. -The \fBXawTextSearch\fP function will begin at the insertion point -and search in the -direction specified for a string that matches the one passed in -\fItext\fP. If the string is found the location of the first -character in the string is returned. If the string could not be -found then the value \fBXawTextSearchError\fP is returned. -.NH 3 -Redisplaying Text -.LP -To redisplay a range of characters, use \fBXawTextInvalidate\fP: -.IN "XawTextInvalidate" "" "@DEF@" -.FD 0 -void XawTextInvalidate(\fIw\fP, \fIfrom\fP, \fIto\fP) -.br - Widget \fIw\fP; -.br - XawTextPosition \fIfrom\fP, \fIto\fP; -.FN -.IP \fIw\fP 1i -Specifies the Text widget. -.IP \fIfrom\fP 1i -Specifies the start of the text to redisplay. -.IP \fIto\fP 1i -Specifies the end of the text to redisplay. -.LP -See section 5.4 for a description of \fBXawTextPosition\fP. -The \fBXawTextInvalidate\fP -function causes the specified range of characters to be redisplayed -immediately if redisplay is enabled or the next time that redisplay is -enabled. -.LP -.sp 1 -To enable redisplay, use \fBXawTextEnableRedisplay\fP: -.IN "XawTextEnableRedisplay" "" "@DEF@" -.FD 0 -void XawTextEnableRedisplay(\fIw\fP) -.br - Widget \fIw\fP; -.FN -.IP \fIw\fP 1i -Specifies the Text widget. -.LP -The \fBXawTextEnableRedisplay\fP function flushes any changes due to -batched updates when \fBXawTextDisableRedisplay\fP -was called and allows future changes to be reflected immediately. -.LP -.sp 1 -To disable redisplay while making several changes, use -\fBXawTextDisableRedisplay\fP. -.IN "XawTextDisableRedisplay" "" "@DEF@" -.FD 0 -void XawTextDisableRedisplay(\fIw\fP) -.br - Widget \fIw\fP; -.FN -.IP \fIw\fP 1i -Specifies the Text widget. -.LP -The \fBXawTextDisableRedisplay\fP function causes all changes to be -batched until either \fBXawTextDisplay\fP or \fBXawTextEnableRedisplay\fP -is called. -.LP -.sp 1 -To display batched updates, use \fBXawTextDisplay\fP: -.IN "XawTextDisplay" "" "@DEF@" -.FD 0 -void XawTextDisplay(\fIw\fP) -.br - Widget \fIw\fP; -.FN -.IP \fIw\fP 1i -Specifies the Text widget. -.LP -The \fBXawTextDisplay\fP function forces any accumulated updates to be -displayed. -.NH 3 -Resources Convenience Routines -.LP -To obtain the character position of the left-most character on the -first line displayed in the widget (the value of the -\fBdisplayPosition\fP resource), use \fBXawTextTopPosition\fP. -.IN "XawTextTopPosition" "" @DEF@" -.FD 0 -XawTextPosition XawTextTopPosition(\fIw\fP) -.br - Widget \fIw\fP; -.FN -.IP \fIw\fP 1i -Specifies the Text widget. -.LP -.sp 1 -To assign a new selection array to a text widget use -\fBXawTextSetSelectionArray\fP: -.IN "XawTextSetSelectionArray" "" "@DEF@" -.FD 0 -void XawTextSetSelectionArray(\fIw\fP, \fIsarray\fP) -.br - Widget \fIw\fP; -.br - XawTextSelectType * \fIsarray\fP; -.FN -.IP \fIw\fP 1i -Specifies the Text widget. -.IP \fIsarray\fP 1i -Specifies a selection array as defined in the section called \fBText -Selections for Application Programmers\fP. -.LP -Calling this function is equivalent to setting the value of the -\fBselectionTypes\fP resource. -.LP -.sp 1 -To move the insertion point to the specified source position, use -\fBXawTextSetInsertionPoint\fP: -.IN "XawTextSetInsertionPoint" "" "@DEF@" -.FD 0 -void XawTextSetInsertionPoint(\fIw\fP, \fIposition\fP) -.br - Widget \fIw\fP; -.br - XawTextPosition \fIposition\fP; -.FN -.IP \fIw\fP 1i -Specifies the Text widget. -.IP \fIposition\fP 1i -Specifies the new position for the insertion point. -.LP -See section 5.4 for a description of \fBXawTextPosition\fP. -The text will be scrolled vertically if necessary to make the line -containing the insertion point visible. Calling this function is -equivalent to setting the \fBinsertPosition\fP resource. -.LP -.sp 1 -To obtain the current position of the insertion point, use -\fBXawTextGetInsertionPoint\fP: -.IN "XawTextGetInsertionPoint" "" "@DEF@" -.FD 0 -XawTextPosition XawTextGetInsertionPoint(\fIw\fP) -.br - Widget \fIw\fP; -.FN -.IP \fIw\fP 1i -Specifies the Text widget. -.LP -See section 5.4 for a description of \fBXawTextPosition\fP. -The result is equivalent to retrieving the value of the -\fBinsertPosition\fP resource. -.LP -.sp 1 -To replace the text source in the specified widget, use -\fBXawTextSetSource\fP: -.IN "XawTextSetSource" "" "@DEF@" -.FD 0 -void XawTextSetSource(\fIw\fP, \fIsource\fP, \fIposition\fP) -.br - Widget \fIw\fP; -.br - Widget \fIsource\fP; -.br - XawTextPosition \fIposition\fP; -.FN -.IP \fIw\fP 1i -Specifies the Text widget. -.IP \fIsource\fP 1i -Specifies the text source object. -.IP \fIposition\fP 1i -Specifies character position that will become the upper left hand corner -of the displayed text. This is usually set to zero. -.LP -See section 5.4 for a description of \fBXawTextPosition\fP. -A display update will be performed if redisplay is enabled. -.LP -.sp 1 -To obtain the current text source for the specified widget, use -\fBXawTextGetSource\fP: -.IN "XawTextGetSource" "" "@DEF@" -.FD 0 -Widget XawTextGetSource(\fIw\fP) -.br - Widget \fIw\fP; -.FN -.IP \fIw\fP 1i -Specifies the Text widget. -.LP -This function returns the text source that this Text widget is currently -using. -.LP -.sp -To enable and disable the insertion point, use -\fBXawTextDisplayCaret\fP: -.IN "XawTextDisplayCaret" "" "@DEF@" -.FD 0 -void XawTextDisplayCaret(\fIw\fP, \fIvisible\fP) -.br - Widget \fIw\fP; -.br - Boolean \fIvisible\fP; -.FN -.IP \fIw\fP 1i -Specifies the Text widget. -.IP \fIvisible\fP 1i -Specifies whether or not the caret should be displayed. -.LP -If \fIvisible\fP is \fBFalse\fP the insertion point will be disabled. -The marker is re-enabled either by setting \fIvisible\fP to \fBTrue\fP, by -calling \fBXtSetValues\fP, or by executing the \fIdisplay-caret\fP -action routine. diff --git a/xc/doc/specs/Xaw/TextSink b/xc/doc/specs/Xaw/TextSink deleted file mode 100644 index db7ddefaa..000000000 --- a/xc/doc/specs/Xaw/TextSink +++ /dev/null @@ -1,420 +0,0 @@ -.\" $XConsortium: TextSink,v 1.16 94/05/02 08:34:43 gildea Exp $ -.NH 2 -TextSink Object -.LP -.XS - TextSink Object -.XE -.IN "TextSink object" "" "@DEF@" -.LP -.Ds 0 -.TA 2.0i -.ta 2.0i -Application Header file <X11/Xaw/TextSink.h> -.IN "TextSink.h" "" -Class Header file <X11/Xaw/TextSinkP.h> -.IN "TextSinkP.h" "" -Class textSinkObjectClass -.IN "textSinkObjectClass" "" -Class Name TextSink -.IN "TextSink object" "class name" -Superclass Object -.De -.LP -The TextSink object is the root object for all text sinks. Any new text -sink objects should be subclasses of the TextSink Object. The TextSink -Class contains all methods that the Text widget expects a text sink to -export. -.LP -Since all text sinks will have some resources in common, the TextSink -defines a few new resources. -.NH 3 -Resources -.LP -When creating an TextSink 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 -foreground Foreground Pixel XtDefaultForeground -.sp 3p -_ -.TE -.Bg Bold -.Dc -.Sg Bold -.NH 3 -Subclassing the TextSink -.IN "TextSink object" "subclassing" "@DEF@" -.LP -The only purpose of the TextSink Object is to be subclassed. It -contains the minimum set of class methods that all text sinks must have. -While all may be inherited, the direct descendant of TextSink \fBmust -specify\fP some of them as TextSink does contain enough information to -be a valid text sink by itself. Do not try to use -the TextSink as a valid sink for the Text widget; it is not intended -to be used as a sink by itself. -.TS H -lw(1i) lw(1.5i) lw(2i) lw(1i). -_ -.sp 3p -.TB -Function Inherit with Public Interface must specify -.sp 3p -_ -.TH -.R -.sp 3p -DisplayText XtInheritDisplayText XawTextSinkDisplayText yes -.IN "XtInheritDisplayText" "" -.IN "XawTextSinkDisplayText" "" -InsertCursor XtInheritInsertCursor XawTextSinkInsertCursor yes -.IN "XtInheritInsertCursor" "" -.IN "XawTextSinkInsertCursor" "" -ClearToBackground XtInheritClearToBackground XawTextSinkClearToBackground no -.IN "XtInheritClearToBackground" "" -.IN "XawTextSinkClearToBackground" "" -FindPosition XtInheritFindPosition XawTextSinkFindPosition yes -.IN "XtInheritFindPosition" "" -.IN "XawTextSinkFindPosition" "" -FindDistance XtInheritFindDistance XawTextSinkFindDistance yes -.IN "XtInheritFindDistance" "" -.IN "XawTextSinkFindDistance" "" -Resolve XtInheritResolve XawTextSinkResolve yes -.IN "XtInheritResolve" "" -.IN "XawTextSinkResolve" "" -MaxLines XtInheritMaxLines XawTextSinkMaxLines no -.IN "XtInheritMaxLines" "" -.IN "XawTextSinkMaxLines" "" -MaxHeight XtInheritMaxHeight XawTextSinkMaxHeight no -.IN "XtInheritMaxHeight" "" -.IN "XawTextSinkMaxHeight" "" -SetTabs XtInheritSetTabs XawTextSinkSetTabs no -.IN "XtInheritSetTabs" "" -.IN "XawTextSinkSetTabs" "" -GetCursorBounds XtInheritGetCursorBounds XawTextSinkGetCursorBounds yes -.IN "XtInheritGetCursorBounds" "" -.IN "XawTextSinkGetCursorBounds" "" -_ -.TE -.NH 4 -Displaying Text -.LP -To display a section of the text buffer contained in the text source -use the function \fBDisplayText\fP: -.IN "TextSink object" "DisplayText" "@DEF@" -.FD 0 -void DisplayText(\fIw\fP, \fIx\fP, \fIy\fP, \fIpos1\fP, \fIpos2\fP, \fIhighlight\fP) -.br - Widget \fIw\fP; -.br - Position \fIx\fP, \fIy\fP; -.br - XawTextPosition \fIpos1\fP, \fIpos2\fP; -.br - Boolean \fIhighlight\fP; -.FN -.IP \fIw\fP 1i -Specifies the TextSink object. -.IP \fIx\fP 1i -Specifies the x location to start drawing the text. -.IP \fIy\fP 1i -Specifies the y location to start drawing text. -.IP \fIpos1\fP 1i -Specifies the location within the text source of the first character -to be printed. -.IP \fIpos2\fP 1i -Specifies the location within the text source of the last character -to be printed. -.IP \fIhighlight\fP 1i -Specifies whether or not to paint the text region highlighted. -.LP -The Text widget will only pass one line at a time to the text sink, so -this function does not need to know how to line feed the text. It is -acceptable for this function to just ignore Carriage Returns. \fIx\fP -and \fIy\fP denote the upper left hand corner of the first character to -be displayed. -.NH 4 -Displaying the Insert Point -.LP -The function that controls the display of the text cursor is -\fBInsertCursor\fP. This function will be called whenever the text -widget desires to change the state of, or move the insert point. -.FD 0 -void InsertCursor(\fIw\fP, \fIx\fP, \fIy\fP, \fIstate\fP) -.IN "TextSink object" "InsertCursor" "@DEF@" -.br - Widget \fIw\fP; -.br - Position \fIx\fP, \fIy\fP; -.br - XawTextInsertState \fIstate\fP; -.FN -.IP \fIw\fP 1i -Specifies the TextSink object. -.IP \fIx\fP 1i -Specifies the x location of the cursor in Pixels. -.IP \fIy\fP 1i -Specifies the y location of the cursor in Pixels. -.IP \fIstate\fP 1i -Specifies the state of the cursor, may be one of \fBXawisOn\fP or -\fBXawisOff\fP. -.LP -\fIX\fP and \fIy\fP denote the upper left hand corner of the insert point. -.NH 4 -Clearing Portions of the Text window -.LP -To clear a portion of the Text window to its background color, the Text -widget will call \fBClearToBackground\fP. The TextSink object already -defines this function as calling \fBXClearArea\fP on the region passed. -This behavior will be used if you specify -\fBXtInheritClearToBackground\fP for this method. -.IN "XtInheritClearToBackground" "" -.IN "TextSink object" "ClearToBackground" "@DEF@" -.FD 0 -void ClearToBackground(\fIw\fP, \fIx\fP, \fIy\fP, \fIwidth\fP, \fIheight\fP) -.br - Widget \fIw\fP; -.br - Position \fIx\fP, \fIy\fP; -.br - Dimension \fIwidth\fP, \fIheight\fP; -.FN -.IP \fIw\fP 1i -Specifies the TextSink object. -.IP \fIx\fP 1i -Specifies the x location, in pixels, of the Region to clear. -.IP \fIy\fP 1i -Specifies the y location, in pixels, of the Region to clear. -.IP \fIwidth\fP 1i -Specifies the width, in pixels, of the Region to clear. -.IP \fIheight\fP 1i -Specifies the height, in pixels, of the Region to clear. -.LP -\fIX\fP and \fIy\fP denote the upper left hand corner of region to clear. -.NH 4 -Finding a Text Position Given Pixel Values -.LP -To find the text character position that will be rendered at a given x -location the Text widget uses the function \fBFindPosition\fP: -.IN "TextSink object" "FindPosition" "@DEF@" -.FD 0 -void FindPosition(\fIw\fP, \fIfromPos\fP, \fIfromX\fP, \fIwidth\fP, \fIstopAtWordBreak\fP, \fIpos_return\fP, \fIwidth_return\fP, \fIheight_return\fP) -.br - Widget \fIw\fP; -.br - XawTextPosition \fIfromPos\fP; -.br - int \fIfromX\fP, \fIwidth\fP; -.br - Boolean \fIstopAtWordBreak\fP; -.br - XawTextPosition \fI*pos_return\fP; -.br - int \fI*width_return\fP, \fI*height_return\fP; -.FN -.IP \fIw\fP 1.25i -Specifies the TextSink object. -.IP \fIfromPos\fP 1.25i -Specifies a reference position, usually the first character in this line. -This character is always to the left of the desired character location. -.IP \fIfromX\fP 1.25i -Specifies the distance that the left edge of \fIfromPos\fP is from the -left edge of the window. This is the reference x location for the -reference position. -.IP \fIwidth\fP 1.25i -Specifies the distance, in pixels, from the reference position to the -desired character position. -.IP \fIstopAtWordBreak\fP 1.25i -Specifies whether or not the position that is returned should be forced -to be on a word boundary. -.IP \fIpos_return\fP 1.25i -Returns the character position that corresponds to the location that has -been specified, or the work break immediately to the left of the -position if \fIstopAtWordBreak\fP is \fBTrue\fP. -.IP \fIwidth_return\fP 1.25i -Returns the actual distance between \fIfromPos\fP and \fIpos_return\fI. -.IP \fIheight_return\fP 1.25i -Returns the maximum height of the text between \fIfromPos\fP and -\fIpos_return\fI. -.LP -This function need make no attempt to deal with line feeds. The text -widget will only call it one line at a time. -.LP -.sp -Another means of finding a text position is provided by the \fBResolve\fP -function: -.IN "TextSink object" "Resolve" "@DEF@" -.FD 0 -void Resolve(\fIw\fP, \fIfromPos\fP, \fIfromX\fP, \fIwidth\fP, \fIpos_return\fP) -.br - Widget \fIw\fP; -.br - XawTextPosition \fIfromPos\fP; -.br - int \fIfromX\fP, \fIwidth\fP; -.br - XawTextPosition \fI*pos_return\fP; -.FN -.IP \fIw\fP 1i -Specifies the TextSink object. -.IP \fIfromPos\fP 1i -Specifies a reference position, usually the first character in this line. -This character is always to the left of the desired character location. -.IP \fIfromX\fP 1i -Specifies the distance that the left edge of \fIfromPos\fP is from the -left edge of the window. This is the reference x location for the -reference position. -.IP \fIwidth\fP 1i -Specifies the distance, in pixels, from the reference position to the -desired character position. -.IP \fIpos_return\fP 1i -Returns the character position that corresponds to the -location that has been specified, or the word break immediately to the left -if \fIstopAtWordBreak\fP is \fBTrue\fP. -.LP -This function need make no attempt to deal with line feeds. The text -widget will only call it one line at a time. This is a more convenient -interface to the \fBFindPosition\fP function, and provides a subset of its -functionality. -.IN "FindPosition" "" -.NH 4 -Finding the Distance Between two Text Positions -.LP -To find the distance in pixels between two text positions on the same -line use the function \fBFindDistance\fP. -.IN "TextSink object" "FindDistance" "@DEF@" -.FD 0 -void FindDistance(\fIw\fP, \fIfromPos\fP, \fIfromX\fP, \fItoPos\fP, \fIwidth_return\fP, \fIpos_return\fP, \fIheight_return\fP) -.br - Widget \fIw\fP; -.br - XawTextPosition \fIfromPos\fP, \fItoPos\fP; -.br - int \fIfromX\fP; -.br - XawTextPosition \fI*pos_return\fP; -.br - int \fI*width_return\fP, \fI*height_return\fP; -.FN -.IP \fIw\fP 1i -Specifies the TextSink object. -.IP \fIfromPos\fP 1i -Specifies the text buffer position, in characters, of the first position. -.IP \fIfromX\fP 1i -Specifies the distance that the left edge of \fIfromPos\fP is from the -left edge of the window. This is the reference x location for the -reference position. -.IP \fItoPos\fP 1i -Specifies the text buffer position, in characters, of the second position. -.IP \fIresWidth\fP 1i -Return the actual distance between \fIfromPos\fP -and \fIpos_return\fI. -.IP \fIresPos\fP 1i -Returns the character position that corresponds to the actual character -position used for \fItoPos\fP in the calculations. This may be -different than \fItoPos\fP, for example if \fIfromPos\fP and \fItoPos\fP -are on different lines in the file. -.IP \fIheight_return\fP 1i -Returns the maximum height of the text between \fIfromPos\fP and -\fIpos_return\fP. -.LP -This function need make no attempt to deal with line feeds. The Text -widget will only call it one line at a time. -.NH 4 -Finding the Size of the Drawing area -.LP -To find the maximum number of lines that will fit into the current Text -widget, use the function \fBMaxLines\fP. The TextSink already defines -this function to compute the maximum number of lines by using the height -of \fBfont\fP. -.IN "TextSink object" "MaxLines" "@DEF@" -.FD 0 -int MaxLines(\fIw\fP, \fIheight\fP) -.br - Widget \fIw\fP; -.br - Dimension \fIheight\fP; -.FN -.IP \fIw\fP 1i -Specifies the TextSink object. -.IP \fIheight\fP 1i -Specifies the height of the current drawing area. -.LP -Returns the maximum number of lines that will fit in \fIheight\fP. -.LP -.sp -To find the height required for a given number of text lines, use -the function \fBMaxHeight\fP. The TextSink already defines this -function to compute the maximum height of the window by using the -height of \fBfont\fP. -.IN "TextSink object" "MaxHeight" "@DEF@" -.FD 0 -int MaxHeight(\fIw\fP, \fIlines\fP) -.br - Widget \fIw\fP; -.br - int \fIlines\fP; -.FN -.IP \fIw\fP 1i -Specifies the TextSink object. -.IP \fIheight\fP 1i -Specifies the height of the current drawing area. -.LP -Returns the height that will be taken up by the number of lines passed. -.NH 4 -Setting the Tab Stops -.LP -To set the tab stops for a text sink use the \fBSetTabs\fP function. -The TextSink already defines this function to set the tab x location in -pixels to be the number of characters times the figure width of -\fBfont\fP. -.IN "TextSink object" "SetTabs" "@DEF@" -.FD 0 -void SetTabs(\fIw\fP, \fItab_count\fP, \fItabs\fP) -.br - Widget \fIw\fP; -.br - int \fItab_count\fP, \fI*tabs\fP; -.FN -.IP \fIw\fP 1i -Specifies the TextSink object. -.IP \fItab_count\fP 1i -Specifies the number of tabs passed in \fItabs\fP. -.IP \fItabs\fP 1i -Specifies the position, in characters, of the tab stops. -.LP -This function is responsible for the converting character positions passed -to it into whatever internal positions the TextSink uses for tab placement. -.NH 4 -Getting the Insert Point's Size and Location -.LP -To get the size and location of the insert point use the -\fBGetCursorBounds\fP function. -.IN "TextSink object" "GetCursorBounds" "@DEF@" -.FD 0 -void GetCursorBounds(\fIw\fP, \fIrect_return\fP) -.br -Widget \fIw\fP; -.br -XRectangle \fI*rect_return\fP; -.FN -.IP \fIw\fP 1i -Specifies the TextSinkObject. -.IP \fIrect_return\fP 1i -Returns the location and size of the insert point. -.LP -\fIRect\fP will be filled with the current size and location of the -insert point. diff --git a/xc/doc/specs/Xaw/TextSource b/xc/doc/specs/Xaw/TextSource deleted file mode 100644 index 59a9c0846..000000000 --- a/xc/doc/specs/Xaw/TextSource +++ /dev/null @@ -1,330 +0,0 @@ -.\" $XConsortium: TextSource,v 1.15 94/05/02 08:34:42 gildea Exp $ -.NH 2 -TextSrc Object -.LP -.XS - TextSrc Object -.XE -.IN "TextSrc object" "" "@DEF@" -.LP -.Ds 0 -.TA 2.0i -.ta 2.0i -Application Header file <X11/Xaw/TextSrc.h> -.IN "TextSrc.h" "" -Class Header file <X11/Xaw/TextSrcP.h> -.IN "TextSrcP.h" "" -Class textSrcObjectClass -.IN "textSrcObjectClass" "" -Class Name TextSrc -.IN "TextSrc object" "class name" -Superclass Object -.De -.LP -The TextSrc object is the root object for all text sources. Any new text -source objects should be subclasses of the TextSrc Object. The -TextSrc Class contains all methods the Text widget expects a text -source to export. -.LP -Since all text sources will have some resources in common the -TextSrc defines a few new resources. -.NH 3 -Resources -.LP -When creating an TextSrc object instance, the following resources are -retrieved from the argument list or from the resource database: -.LP -.IN "TextSrc 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 -destroyCallback Callback XtCallbackList NULL -editType EditType EditMode NULL -.sp 3p -_ -.TE -.Dc -.Oe Bold -.NH 3 -Subclassing the TextSrc -.IN "TextSrc object" "subclassing" "@DEF@" -.LP -The only purpose of the TextSrc Object is to be subclassed. It contains -the minimum set of class methods that all text sources must have. All -class methods of the TextSrc must be defined, as the Text widget uses -them all. While all may be inherited, the direct descendant of TextSrc -\fBmust\fP specify some of them as TextSrc does not contain enough -information to be a valid text source by itself. Do not try to use the -TextSrc as a valid source for the Text widget; it is not intended to be -used as a source by itself and bad things will probably happen. -.TS H -lw(1i) lw(1.5i) lw(2i) lw(1i). -_ -.sp 3p -.TB -Function Inherit with Public Interface must specify -.sp 3p -_ -.TH -.R -.sp 3p -Read XtInheritRead XawTextSourceRead yes -.IN "XtInheritRead" "" -.IN "XawTextSourceRead" "" -Replace XtInheritReplace XawTextSourceReplace no -.IN "XtInheritReplace" "" -.IN "XawTextSourceReplace" "" -Scan XtInheritScan XawTextSourceScan yes -.IN "XtInheritScan" "" -.IN "XawTextSourceScan" "" -Search XtInheritSearch XawTextSourceSearch no -.IN "XtInheritSearch" "" -.IN "XawTextSourceSearch" "" -SetSelection XtInheritSetSelection XawTextSourceSetSelection no -.IN "XtInheritSetSelection" "" -.IN "XawTextSourceSetSelection" "" -ConvertSelection XtInheritConvertSelection XawTextSourceConvertSelection no -.IN "XtInheritConvertSelection" "" -.IN "XawTextSourceConvertSelection" "" -_ -.TE -.NH 4 -Reading Text. -.LP -To read the text in a text source use the \fBRead\fP function: -.IN "TextSrc object" "Read" "@DEF@" -.FD 0 -XawTextPosition Read(\fIw\fP, \fIpos\fP, \fItext_return\fP, \fIlength\fP) -.br -Widget \fIw\fP; -.br -XawTextPosition \fIpos\fP; -.br -XawTextBlock \fI*text_return\fP; -.br -int \fIlength\fP; -.FN -.IP \fIw\fP 1i -Specifies the TextSrc object. -.IP \fIpos\fP 1i -Specifies the position of the first character to be read from the text buffer. -.IP \fItext\fP 1i -Returns the text read from the source. -.IP \fIlength\fP 1i -Specifies the maximum number of characters the TextSrc should -return to the application in \fItext_return\fP. -.LP -This function returns the actual number of characters read from the -text buffer. The function is not required to return \fIlength\fP -characters if that many characters are in the file, it may break at -any point that is convenient to the internal structure of the -source. It may take several calls to \fBRead\fP before the desired -portion of the text buffer is fully retrieved. -.NH 4 -Replacing Text. -.LP -To replace or edit the text in a text buffer use the \fBReplace\fP function: -.FD 0 -XawTextPosition Replace(\fIw\fP, \fIstart\fP, \fIend\fP, \fItext\fP) -.IN "TextSrc object" "Replace" @DEF@ -.br -Widget \fIw\fP; -.br -XawTextPosition \fIstart\fP, \fIend\fP; -.br -XawTextBlock \fI*text\fP; -.FN -.IP \fIw\fP 1i -Specifies the TextSrc object. -.IP \fIstart\fP 1i -Specifies the position of the first character to be removed from the text -buffer. This is also the location to begin inserting the new text. -.IP \fIend\fP 1i -Specifies the position immediately after the last character to be -removed from the text buffer. -.IP \fItext\fP 1i -Specifies the text to be added to the text source. -.LP -This function can return any of the following values: -.IP \fBXawEditDone\fP 1.25i -.IN "XawEditDone" "" -The text replacement was successful. -.IP \fBXawPositionError\fP 1.25i -.IN "XawPositionError" "" -The edit mode is \fBXawtextAppend\fP and \fIstart\fP is not the last -character of the source. -.IP \fBXawEditError\fP 1.25i -.IN "XawEditError" "" -Either the Source was read-only or the range to be deleted is larger -than the length of the Source. -.LP -The \fBReplace\fP arguments \fIstart\fP and \fIend\fP represent the -text source character positions for the existing text that is to be -replaced by the text in the text block. The characters from -\fIstart\fP up to but not including \fIend\fP are deleted, and the -buffer specified by the text block is inserted in their -place. If \fIstart\fP and \fIend\fP are equal, no text is deleted and -the new text is inserted after \fIstart\fP. -.NH 4 -Scanning the TextSrc -.LP -To search the text source for one of the predefined boundary types use -the \fBScan\fP function: -.FD 0 -XawTextPosition Scan(\fIw\fP, \fIposition\fP, \fItype\fP, \fIdir\fP, \fIcount\fP, \fIinclude\fP) -.IN "TextSrc object" "Scan" @DEF@ -.br -Widget \fIw\fP; -.br -XawTextPosition \fIposition\fP; -.br -XawTextScanType \fItype\fP; -.br -XawTextScanDirection \fIdir\fP; -.br -int \fIcount\fP; -.br -Boolean \fIinclude\fP; -.FN -.IP \fIw\fP 1i -Specifies the TextSrc object. -.IP \fIposition\fP 1i -Specifies the position to begin scanning the source. -.IP \fItype\fP 1i -Specifies the type of boundary to scan for, may be one of: -\fBXawstPosition\fP, \fBXawstWhiteSpace\fP, \fBXawstEOL\fP, -.IN "XawstPositions" "" -.IN "XawstWhiteSpace" "" -.IN "XawstEOL" "" -\fBXawstParagraph\fP, \fBXawstAll\fP. The exact meaning of these -.IN "XawstParagraph" "" -.IN "XawstAll" "" -boundaries is left up to the individual text source. -.IP \fIdir\fP 1i -Specifies the direction to scan, may be either \fBXawsdLeft\fP to search -.IN "XawsdLeft" "" -backward, or \fBXawsdRight\fP to search forward. -.IN "XawsdRight" "" -.IP \fIcount\fP 1i -Specifies the number of boundaries to scan for. -.IP \fIinclude\fP 1i -Specifies whether the boundary itself should be included in the scan. -.LP -The \fBScan\fP function returns the position in the text source of the desired -boundary. It is expected to return a valid address for -all calls made to it, thus if a particular request is made that would take -the text widget beyond the end of the source it must return the -position of that end. -.NH 4 -Searching through a TextSrc -.LP -To search for a particular string use the \fBSearch\fP function. -.FD 0 -XawTextPosition Search(\fIw\fP, \fIposition\fP, \fIdir\fP, \fItext\fP) -.IN "TextSrc object" "Search" @DEF@ -.br -Widget \fIw\fP; -.br -XawTextPosition \fIposition\fP; -.br -XawTextScanDirection \fIdir\fP; -.br -XawTextBlock \fI*text\fP; -.FN -.IP \fIw\fP 1i -Specifies the TextSrc object. -.IP \fIposition\fP 1i -Specifies the position to begin the search. -.IP \fIdir\fP 1i -Specifies the direction to search, may be either \fBXawsdLeft\fP to search -.IN "XawsdLeft" "" -backward, or \fBXawsdRight\fP to search forward. -.IN "XawsdRight" "" -.IP \fItext\fP 1i -Specifies a text block containing the text to search for. -.LP -This function will search through the text buffer attempting to find a -match for the string in the text block. If a match is found in the -direction specified, then the character location of the first character -in the string is returned. If no text was found then -\fBXawTextSearchError\fP is returned. -.IN "XawTextSearchError" "" -.NH 4 -Text Selections -.LP -While many selection types are handled by the Text widget, text sources -may have selection types unknown to the Text widget. When a selection -conversion is requested by the X server the Text widget will first call -the \fBConvertSelection\fP function, to attempt the selection -conversion. -.FD 0 -Boolean ConvertSelections(\fIw\fP, \fIselection\fP, \fItarget\fP, \fItype\fP, \fIvalue_return\fP, \fIlength_return\fP, \fIformat_return\fP) -.IN "Text widget" "ConvertSelection" @DEF@ -.br -Widget \fIw\fP; -.br -Atom \fI*selection\fP, \fI*target\fP, \fI*type\fP; -.br -caddr_t \fI*value_return\fP; -.br -unsigned long \fI*length_return\fP; -.br -int \fI*format_return\fP; -.FN -.IP \fIw\fP 1i -Specifies the TextSrc object. -.IP \fIselection\fP 1i -Specifies the type of selection that was requested (e.g. \fBPRIMARY\fP). -.IP \fItarget\fP 1i -Specifies the type of the selection that has been requested, which -indicates the desired information about the selection (e.g. Filename, -Text, Window). -.IP \fItype\fP 1i -Specifies a pointer to the atom into which the property type of the converted -value of the selection is to be stored. For instance, either file -name or text might have property type \fBXA_STRING\fP. -.IP \fIvalue_return\fP 1i -Returns a pointer into which a pointer to the converted value of the -selection -is to be stored. The selection owner is responsible for allocating -this storage. The memory is considered owned by the toolkit, and is -freed by XtFree when the Intrinsics selection mechanism is done with it. -.IP \fIlength_return\fP 1i -Returns a pointer into which the number of elements in value is to be stored. -The size of each element is determined by \fIformat\fP. -.IP \fIformat_return\fP 1i -Returns a pointer into which the size in bits of the data elements of the -selection value is to be stored. -.LP -If this function returns \fBTrue\fP then the Text widget will assume -that the source has taken care of converting the selection, Otherwise the -Text widget will attempt to convert the selection itself. -.LP -.sp -If the source needs to know when the text selection is modified it -should define a \fBSetSelection\fP procedure: -.FD 0 -void SetSelection(\fIw\fP, \fIstart\fP, \fIend\fP, \fIselection\fP) -Widget \fIw\fP; -.IN "SetSelection" "" @DEF@ -.br -XawTextPosition \fIstart\fP, \fIend\fP; -.br -Atom \fIselection\fP; -.FN -.IP \fIw\fP 1i -Specifies the TextSrc object. -.IP \fIstart\fP 1i -Specifies the character position of the beginning of the new text selection. -.IP \fIend\fP -Specifies the character position of the end of the new text selection. -.IP \fIselection\fP 1i -Specifies the type of selection that was requested (e.g. \fBPRIMARY\fP). diff --git a/xc/doc/specs/Xaw/Toggle b/xc/doc/specs/Xaw/Toggle deleted file mode 100644 index a7576da26..000000000 --- a/xc/doc/specs/Xaw/Toggle +++ /dev/null @@ -1,370 +0,0 @@ -.\" $XConsortium: Toggle,v 1.25 94/05/02 08:14:37 gildea Exp $ -.NH 2 -Toggle Widget -.XS - Toggle Widget -.XE -.IN "Toggle widget" "" "@DEF@" -.Ds 0 -.TA 2.0i -.ta 2.0i -.sp -Application Header file <Xaw/Toggle.h> -.IN "Toggle.h" "" -Class Header file <Xaw/ToggleP.h> -.IN "ToggleP.h" "" -Class toggleWidgetClass -.IN "toggleWidgetClass" "" -Class Name Toggle -.IN "Toggle widget" "class name" -Superclass Command -.sp -.De -.LP -The Toggle widget is an area, often rectangular, -that displays a graphic. The graphic may be a text -string containing multiple lines of characters in an 8 -bit or 16 bit character set (to be displayed with a -\fIfont\fP), or in a multi-byte encoding (for use with -a \fIfontset\fP). The graphic may also be a bitmap or -pixmap. -.LP -This widget maintains a Boolean state (e.g. -True/False or On/Off) and changes state whenever it is selected. When -the pointer is on the Toggle widget, the Toggle widget may become highlighted by -drawing a rectangle around its perimeter. This highlighting indicates -that the Toggle widget is ready for selection. When pointer button 1 is -pressed and released, the Toggle widget indicates that it has changed -state by reversing its foreground and background colors, and its -\fBnotify\fP action is invoked, calling all functions on its callback -list. If the pointer is moved off of the widget before the pointer button is -released, the Toggle widget reverts to its previous foreground and background -colors, and releasing the pointer button has no effect. This behavior allows -the user to cancel the operation. -.LP -Toggle widgets may also be part of a ``radio group.'' A radio group is a -.IN "Radio groups" "" -.IN "Radio button" "" -.IN "Toggle widget" "used in radio groups" -list of at least two Toggle widget in which no more than one Toggle may -be set at -any time. A radio group is identified by the widget ID of any one of -its members. The convenience routine \fBXawToggleGetCurrent\fP will -return information about the Toggle widget in the radio group. -.LP -Toggle widget state is preserved across changes in sensitivity. -.NH 3 -Resources -.LP -When creating a Toggle widget instance, the following resources are -retrieved from the argument list or from the resource database: -.LP -.IN "Toggle 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 -bitmap Bitmap Pixmap None -borderColor BorderColor Pixel XtDefaultForeground -borderPixmap Pixmap Pixmap XtUnspecifiedPixmap -borderWidth BorderWidth Dimension 1 -callback Callback XtCallbackList NULL -colormap Colormap Colormap Parent's Colormap -cornerRoundPercent CornerRoundPercent Dimension 25 -cursor Cursor Cursor None -cursorName Cursor String NULL -depth Depth int C Parent's Depth -destroyCallback Callback XtCallbackList NULL -encoding Encoding UnsignedChar XawTextEncoding8bit -font Font XFontStruct XtDefaultFont -fontSet FontSet XFontSet XtDefaultFontSet -foreground Foreground Pixel XtDefaultForeground -height Height Dimension A graphic height + 2 * \fBinternalHeight\fP -highlightThickness Thickness Dimension A 2 (0 if Shaped) -insensitiveBorder Insensitive Pixmap GreyPixmap -internalHeight Height Dimension 2 -internalWidth Width Dimension 4 -international International Boolean C False -justify Justify Justify XtJustifyCenter (center) -label Label String name of widget -leftBitmap LeftBitmap Bitmap None -mappedWhenManaged MappedWhenManaged Boolean True -pointerColor Foreground Pixel XtDefaultForeground -pointerColorBackground Background Pixel XtDefaultBackground -radioData RadioData Pointer Name of widget -radioGroup Widget Widget No radio group -resize Resize Boolean True -screen Screen Screen R Parent's Screen -sensitive Sensitive Boolean True -shapeStype ShapeStyle ShapeStyle Rectangle -state State Boolean Off -translations Translations TranslationTable See below -width Width Dimension A graphic width + 2 * \fBinternalWidth\fP -x Position Position 0 -y Position Position 0 -.sp 3p -_ -.TE -.Ac -.As -.Bg -.Gp -.Bm -.Bc -.Bp -.Bw -.Cb -.Cm -.Cr -.Cu -.Cn -.Dp -.Dc -.Le -.Lf -.Ls -.Lg -.Hw -.Ht -.Ib -.Ih -.In -.Ju -.La -.Ll -.Mm -.Pf -.Pb -.IP \fBradioData\fP 1.5i -Specifies the data that will be returned by \fBXawToggleGetCurrent\fP -when this is the currently \fIset\fP widget in the radio group. This -value is also used to identify the Toggle that will be set by a call to -\fBXawToggleSetCurrent\fP. The value NULL will be returned by -\fBXawToggleGetCurrent\fP if no widget in a radio group is currently -set. Programmers must not specify NULL (or Zero) as \fBradioData\fP. -.IP \fBradioGroup\fP 1.5i -Specifies another Toggle widget that is in the radio group to which this -Toggle widget should be added. A radio group is a group of at least two Toggle -widgets, only one of which may be \fIset\fP at a time. If this value is -NULL (the default) then the Toggle will not be part of any radio group -and can change state without affecting any other Toggle widgets. If the -widget specified in this resource is not already in a radio group then a -new radio group will be created containing these two Toggle widgets. No -Toggle widget can be in multiple radio groups. The behavior of a radio -group of one toggle is undefined. A converter is registered which will -convert widget names to widgets without caching. -.Re -.Sc -.Se -.Ss -.IP \fBstate\fP -Specifies whether the Toggle widget is set (\fBTrue\fP) or unset -(\fBFalse\fP). -.Tr -.Xy -.NH 3 -Toggle Actions -.IN "Toggle widget" "actions" -.LP -The Toggle widget supports the following actions: -.IP \(bu 5 -Switching the Toggle widget between the foreground and background -colors with \fBset\fP and \fBunset\fP and \fBtoggle\fP -.IP \(bu 5 -Processing application callbacks with \fBnotify\fP -.IP \(bu 5 -Switching the internal border between highlighted -and unhighlighted states with \fBhighlight\fP and \fBunhighlight\fP -.LP -The following are the default translation bindings used by the -Toggle widget: -.IN "Toggle widget" "default translation table" -.LP -.sp -.Ds 0 -.TA .5i 2.25i -.ta .5i 2.25i - <EnterWindow>: highlight(Always) - <LeaveWindow>: unhighlight(\|) - <Btn1Down>,<Btn1Up>: toggle(\|) notify(\|) -.De -.NH 3 -Toggle Actions -.LP -The full list of actions supported by Toggle is: -.IP \fBhighlight\fP(\fIcondition\fP) 1.5i -Displays the internal highlight border in the color (\fBforeground\fP -or \fBbackground\fP ) that contrasts with the interior color of the -Toggle widget. The conditions \fBWhenUnset\fP and \fBAlways\fP are -understood by this action procedure. If no argument is passed then -\fBWhenUnset\fP is assumed. -.IP \fBunhighlight\fP(\|) 1.5i -Displays the internal highlight border in the color (\fBforeground\fP -or \fBbackground\fP ) that matches the interior color of the -Toggle widget. -.IP \fBset\fP(\|) 1.5i -Enters the \fIset\fP state, in which \fBnotify\fP is possible. This -action causes the Toggle widget to display its interior in the -\fBforeground\fP color. The label or bitmap is displayed in the -\fBbackground\fP color. -.IP \fBunset\fP(\|) 1.5i -Cancels the \fIset\fP state and displays the interior of the Toggle widget in the -\fBbackground\fP color. The label or bitmap is displayed in the -\fBforeground\fP color. -.IP \fBtoggle\fP(\|) 1.5i -Changes the current state of the Toggle widget, causing to be set -if it was previously unset, and unset if it was previously set. -If the widget is to be set, and is in a radio group then this procedure may -unset another Toggle widget causing all routines on its callback list -to be invoked. The callback routines for the Toggle that -is to be unset will be called before the one that is to be set. -.IP \fBreset\fP(\|) 1.5i -Cancels any \fBset\fP or \fBhighlight\fP and displays the interior of the -Toggle widget in the \fBbackground\fP color, with the label displayed in the -\fBforeground\fP color. -.IP \fBnotify\fP(\|) 1.5i -When the Toggle widget is in the \fBset\fP state this action calls all functions in -the callback list named by the \fBcallback\fP resource. The value of -the call_data argument in these callback functions is undefined. -.LP -.NT -When a bitmap of depth greater that one (1) is specified the -\fIset\fP(), \fIunset\fP(), and \fIreset\fP() actions have no effect, -since there are no foreground and background colors used in a -multi-plane pixmap. -.NE -.NH 3 -Radio Groups -.IN "Radio groups" -.LP -There are typically two types of radio groups desired by applications. -The default translations for the Toggle widget implement a "zero or one -.IN "Radio groups" "zero or one of many" -of many" radio group. This means that there may be no more than one -Toggle widget active, but there need not be any Toggle widgets active. -.LP -The other type of radio group is "one of many" and has the more strict -.IN "Radio groups" "one of many" -policy that there will always be exactly one radio button active. -Toggle widgets can be used to provide this interface with a slight -modification to the translation table of each Toggle in the group. -.Ds 0 -.TA .5i 2.25i -.ta .5i 2.25i -.sp - <EnterWindow>: highlight(Always) - <LeaveWindow>: unhighlight(\|) - <Btn1Down>,<Btn1Up>: set(\|) notify(\|) -.sp -.De -This translation table will not allow any Toggle to be \fIunset\fP -except as a result of another Toggle becoming \fIset\fP. It is -the application programmer's responsibility to choose an initial -state for the radio group by setting the \fBstate\fP resource of one of -its member widgets to \fBTrue\fP. -.NH 3 -Convenience Routines -.LP -The following functions allow easy access to the Toggle widget's radio -group functionality. -.NH 4 -Changing the Toggle's Radio Group. -.LP -To enable an application to change the Toggle's radio group, add -the Toggle to a radio group, or remove the Toggle from a radio group, use -\fBXawToggleChangeRadioGroup\fP. -.IN "XawToggleChangeRadioGroup" "" "@DEF@" -.FD -void XawToggleChangeRadioGroup(\fIw\fP, \fIradio_group\fP) -.br - Widget \fIw\fP, \fIradio_group\fP; -.FN -.IP \fIw\fP 1i -Specifies the Toggle widget. -.IP \fIradio_group\fP 1i -Specifies any Toggle in the new radio group. If NULL then the Toggle -will be removed from any radio group of which it is a member. -.LP -If a Toggle is already \fIset\fP in the new radio group, -and the Toggle to be added is also \fIset\fP then the previously -\fIset\fP Toggle in the radio group is \fIunset\fP and its callback -procedures are invoked. -.SH -Finding the Currently selected Toggle in a radio group of Toggles -.LP -To find the currently selected Toggle in a radio group of Toggle widgets -use -\fBXawToggleGetCurrent\fP. -.IN "XawToggleGetCurrent" "" "@DEF@" -.FD -XtPointer XawToggleGetCurrent(\fIradio_group\fP); -.br - Widget \fIradio_group\fP; -.FN -.IP \fIradio_group\fP 1i -Specifies any Toggle widget in the radio group. -.LP -The value returned by this function is the -.PN radioData -of the Toggle in this radio group that is currently set. The default -value for -.PN radioData -is the name of that Toggle widget. If no Toggle is set in the radio -group specified then NULL is returned. -.SH -Changing the Toggle that is set in a radio group. -.LP -To change the Toggle that is currently set in a radio group use -\fBXawToggleSetCurrent\fP. -.IN "XawToggleSetCurrent" "" "@DEF@" -.FD -void XawToggleSetCurrent(\fIradio_group\fP, \fIradio_data\fP); -.br - Widget \fIradio_group\fP; - XtPointer \fIradio_data\fP; -.FN -.IP \fIradio_group\fP 1i -Specifies any Toggle widget in the radio group. -.IP \fIradio_data\fP 1i -Specifies the -.PN radioData -identifying the Toggle that should be set in the radio group specified -by the \fIradio_group\fP argument. -.LP -\fBXawToggleSetCurrent\fP locates the Toggle widget to be set by -matching \fIradio_data\fP against the \fBradioData\fP for each Toggle in -the radio group. If none match, \fBXawToggleSetCurrent\fP returns -without making any changes. If more than one Toggle matches, -\fBXawToggleSetCurrent\fP will choose a Toggle to set arbitrarily. If -this causes any Toggle widgets to change state, all routines in their -callback lists will be invoked. The callback routines for a Toggle that -is to be unset will be called before the one that is to be set. -.SH -Unsetting all Toggles in a radio group. -.LP -To unset all Toggle widgets in a radio group use -\fBXawToggleUnsetCurrent\fP. -.IN "XawToggleUnsetCurrent" "" "@DEF@" -.FD -void XawToggleUnsetCurrent(\fIradio_group\fP); -.br - Widget \fIradio_group\fP; -.FN -.IP \fIradio_group\fP 1i -Specifies any Toggle widget in the radio group. -.LP -If this causes a Toggle widget to change state, all routines on its -callback list will be invoked. - diff --git a/xc/doc/specs/Xaw/Tree b/xc/doc/specs/Xaw/Tree deleted file mode 100644 index 719123fb5..000000000 --- a/xc/doc/specs/Xaw/Tree +++ /dev/null @@ -1,181 +0,0 @@ -.\" $XConsortium: Tree,v 1.4 94/05/01 19:21:20 gildea Exp $ -.NH 2 -Tree Widget -.LP -.XS - Tree Widget -.XE -.IN "Tree widget" "" "@DEF@" -.Ds 0 -.TA 2.0i -.ta 2.0i -.sp -Application Header file <X11/Xaw/Tree.h> -.IN "Box.h" "" -Class Header file <X11/Xaw/TreeP.h> -.IN "TreeP.h" "" -Class treeWidgetClass -.IN "treeWidgetClass" "" -Class Name Tree -.IN "Tree widget" "class name" -Superclass Constraint -.sp -.De -.LP -The Tree widget provides geometry management of arbitrary widgets arranged -in a directed, acyclic graph (i.e., a tree). The hierarchy is constructed -by attaching a constraint resource called \fBtreeParent\fP to each widget -indicating which other node in the tree should be treated as the widget's -superior. The structure of the tree is shown by laying out the nodes -in the standard format for tree diagrams with lines drawn connecting each -node with its children. -.LP -The Tree sizes itself according to the needs of its children and is not -intended to be resized by its parent. Instead, it should be placed inside -another composite widget (such as the \fBPorthole\fP or \fBViewport\fP) -that can be used to scroll around in the tree. -.NH 3 -Resources -.LP -When creating a Tree 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 -autoReconfigure AutoReconfigure Boolean False -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 -foreground Foreground Pixel XtDefaultForeground -gravity Gravity XtGravity WestGravity -height Height Dimension A see \fBLayout Semantics\fP -hSpace HSpace Dimension 4 -lineWidth LineWidth Dimension 0 -mappedWhenManaged MappedWhenManaged Boolean True -numChildren ReadOnly Cardinal R 0 -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 -.IP \fBautoReconfigure\fP 1.5i -Whether or not to layout the tree every time a node is added or removed. -.Bg -.Gp -.Bc -.Bp -.Bw -.Ch -.Cm -.Dp -.Dc -.Lg -.IP \fBgravity\fP 1.5i -.IN "conversions" "Gravity" -Specifies the side of the widget from which the tree should grow. Valid -values include \fBWestGravity\fP, \fBNorthGravity\fP, \fBEastGravity\fP, and -\fBSouthGravity\fP. -.Rs "\fP the legal values\fB" -.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. -.IP \fBlineWidth\fP 1.5i -The width of the lines from nodes that do not have a \fBtreeGC\fP -constraint resource to their children. -.Mm -.Nc -.Sc -.Se -.Tr -.Xy -.NH 3 -Constraint Resources -.LP -.IN "Tree widget" "constraint resources" -Each child of the Tree widget must specify its superior node in the tree. In -addition, it may specify a GC to use when drawing a line between it and its -inferior nodes. -.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 -treeGC TreeGC GC NULL -treeParent TreeParent Widget NULL -.sp 3p -_ -.TE -.IP \fBtreeGC\fP 1.5i -This specifies the GC to use when drawing lines between this widget and its -inferiors in the tree. If this resource is not specified, the Tree's -\fBforeground\fP and \fBlineWidth\fP will be used. -.IP \fBtreeParent\fP 1.5i -This specifies the superior node in the tree for this widget. The default is -for the node to have no superior (and to therefore be at the top of the tree). -.NH 3 -Layout Semantics -.IN "Tree widget" "layout semantics" -.LP -Each time a child is managed or unmanaged, the Tree widget will attempt -to reposition the remaining children to fix the shape of the tree if the -.B autoReconfigure -resource is set. Children at the top (most superior) of the tree are -drawn at -the side specified by the -.B gravity -resource. -.LP -After positioning all children, the Tree widget attempts to shrink its -own size to the minimum dimensions required for the layout. -.NH 3 -Convenience Routines -.LP -.IN "Tree widget" "convenience routines" -The most efficient way to layout a tree is to set -.B autoReconfigure -to False and then use the -.B XawTreeForceLayout -routine to arrange the children. -.IN "XawTreeForceLayout" "" "@DEF@" -.FD 0 -void XawTreeForceLayout(\fIw\fP) -.br - Widget \fIw\fP; -.FN -.IP \fIw\fP 1i -Specifies the Tree widget. diff --git a/xc/doc/specs/Xaw/Viewport b/xc/doc/specs/Xaw/Viewport deleted file mode 100644 index 2b409c73d..000000000 --- a/xc/doc/specs/Xaw/Viewport +++ /dev/null @@ -1,156 +0,0 @@ -.\" $XConsortium: Viewport,v 1.18 94/05/01 20:44:57 gildea Exp $ -.NH 2 -Viewport Widget -.LP -.XS - Viewport Widget -.XE -.IN "Viewport widget" "" "@DEF@" -.Ds 0 -.TA 2.0i -.ta 2.0i -.sp -Application Header file <X11/Xaw/Viewport.h> -.IN "Viewport.h" "" -Class Header file <X11/Xaw/ViewportP.h> -.IN "ViewportP.h" "" -Class viewportWidgetClass -.IN "viewportWidgetClass" "" -Class Name Viewport -.IN "Viewport widget" "class name" -Superclass Form -.sp -.De -.LP -The Viewport widget consists of a frame window, one or two Scrollbars, -and an inner window. The size of the frame window is determined by the -viewing size of the data that is to be displayed and the dimensions to -which the Viewport is created. The inner window is the full size of the -data that is to be displayed and is clipped by the frame window. The -Viewport widget controls the scrolling of the data directly. No -application callbacks are required for scrolling. -.LP -When the geometry of the frame window is equal in size to the inner -window, or when the data does not require scrolling, the Viewport widget -automatically removes any scrollbars. The \fBforceBars\fP option causes -the Viewport widget to display all scrollbars permanently. -.NH 3 -Resources -.LP -When creating a Viewport widget instance, the following resources are -retrieved from the argument list or the resource database: -.LP -.IN "Viewport 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 -allowHoriz Boolean Boolean False -allowVert Boolean Boolean False -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 -forceBars Boolean Boolean False -height Height Dimension height of the child -mappedWhenManaged MappedWhenManaged Boolean True -numChildren ReadOnly Cardinal R 0 -reportCallback ReportCallback XtCallbackList NULL -screen Screen Screen R Parent's Screen -sensitive Sensitive Boolean True -translations Translations TranslationTable NULL -useBottom Boolean Boolean False -useRight Boolean Boolean False -width Width Dimension width of the child -x Position Position 0 -y Position Position 0 -.sp 3p -_ -.TE -.Ac -.IP \fBallowHoriz\fP 1.5i -.br -.ns -.IP \fBallowVert\fP 1.5i -If these resources are \fBFalse\fP then the Viewport will never create -a scrollbar in this direction. If it is \fBTrue\fP then the scrollbar will -only appear when it is needed, unless \fBforceBars\fP is \fBTrue\fP. -.As -.Bg -.Gp -.Bc -.Bp -.Bw -.Ch -.Cm -.Dp -.Dc -.IP \fBforceBars\fP 1.5i -When \fBTrue\fP the scrollbars that have been \fIallowed\fP will always be -visible on the screen. If \fBFalse\fP the scrollbars will be visible only -when the inner window is larger than the frame. -.Hw -.Mm -.Nc -.IP \fBreportCallback\fP 1.5i -These callbacks will be executed whenever the Viewport adjusts the viewed -area of the child. The call_data parameter is a pointer to an XawPannerReport -structure. -.Sc -.Se -.Tr -.IP \fBuseBottom\fP 1.5i -.br -.ns -.IP \fBuseRight\fP 1.5i -By default the scrollbars appear on the left and top of the screen. -These resources allow the vertical scrollbar to be placed on the right -edge of the Viewport, and the horizontal scrollbar on the bottom edge of -the Viewport. -.Xy -.NH 3 -Layout Semantics -.LP -.IN "Viewport widget" "layout semantics" -The Viewport widget manages a single child widget. When the size of the -child is larger than the size of the Viewport, the user can interactively -move the child within the Viewport by repositioning the scrollbars. -.LP -The default size of the Viewport before it is realized is the width and/or -height of the child. After it is realized, the Viewport will allow its -child to grow vertically or horizontally if \fBallowVert\fP or -\fBallowHoriz\fP are set, respectively. If the corresponding vertical -or horizontal scrollbar is not enabled, the Viewport will propagate the -geometry request to its own parent and the child will be allowed to change -size only if the Viewport's parent allows it. Regardless of whether or not -scrollbars are enabled in the corresponding direction, if the child requests -a new size smaller than the Viewport size, the change will be allowed only -if the parent of the Viewport allows the Viewport to shrink to the -appropriate dimension. -.LP -The scrollbar children of the Viewport are named \fBhorizontal\fP and -\fBvertical\fP. By using these names the programmer can specify resources -for the individual scrollbars. \fBXtSetValues\fP can be used to modify -the resources dynamically once the widget ID has been obtained with -\fBXtNameToWidget\fP. -.IN "XtNameToWidget" "" -.NT -Although the Viewport is a Subclass of the Form, no resources for the Form -may be supplied for any of the children of the Viewport. These constraints -are managed internally and are not meant for public consumption. -.NE diff --git a/xc/doc/specs/Xaw/Xtk.widg.front b/xc/doc/specs/Xaw/Xtk.widg.front deleted file mode 100644 index 6ffe090a3..000000000 --- a/xc/doc/specs/Xaw/Xtk.widg.front +++ /dev/null @@ -1,134 +0,0 @@ -.\" -.EH '''' -.OH '''' -.EF '''' -.OF '''' -.ps 11 -.nr PS 11 -\& -.sp 8 -.ce 5 -\s+2\fB\*(xW\fP\s-2 - -\s+1\fBX Window System\fP\s-1 - -\s+1\fBX Version 11, Release 3+\fP\s-1 - -\s+1\fBDRAFT - not for Redistribution\fP\s-1 -.sp 6 -.ce 4 -\s-1Ralph R. Swick -.sp 6p -Digital Equipment Corporation -External Research Group -MIT Project Athena -.sp 2 -.ce 4 -Terry Weissman -.sp 6p -Digital Equipment Corporation -Western Software Laboratory\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 -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. -Copyright \(co 1985, 1986, 1987, 1988 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 -.ps 11 -.nr PS 11 -.bp iii -.XS iii -Acknowledgments -.XE -\& -.sp 1 -.ce 3 -\s+1\fBAcknowledgments\fP\s-1 -.sp 2 -.na -.LP -The implementation of the Athena Widgets was the responsibility of -Ralph Swick, Ron Newman (Project Athena), -and Mark Ackerman (Project Athena). -Additional contributions to their implementation was made by: -.LP -.Ds -Rich Hyde (Digital WSL) -Terry Weissman (Digital WSL) -Mary Larson (Digital UEG) -Joel McCormack (Digital WSL) -Jeanne Rich (Digital WSL) -Charles Haynes (Digital WSL) -Loretta Guarino-Reid (Digital WSL) -.De -.LP -The contributors to the X10 toolkit also deserve much of the -credit for this work. -The Athena Widgets borrow heavily on the their counterparts in the X10 toolkit. -The design and implementation of the X10 toolkit were done by: -.LP -.Ds -Terry Weissman (Digital WSL) -Smokey Wallace (Digital WSL) -Phil Karlton (Digital WSL) -Charles Haynes (Digital WSL) -Ram Rao (Digital UEG) -Mary Larson (Digital UEG) -Mike Gancarz (Digital UEG) -Kathleen Langone (Digital UEG) -.De -.LP -Thanks go to Al Mento of Digital's UEG Documentation Group for -formatting and generally improving this document -and to Chris Peterson of Project Athena for testing the many versions -of the code and reviewing this document. -.LP -.sp -.Ds 0 -Ralph R. Swick -Digital Equipment Corporation -External Research Group -MIT Project Athena -.De -.bp 1 -.EH '\fBX Toolkit Athena Widgets\fP''\fBX11, Release 3+ DRAFT\fP' -.OH '\fBX Toolkit Athena Widgets\fP''\fBX11, Release 3+ DRAFT\fP' -.EF ''\fB % \fP'' -.OF ''\fB % \fP'' diff --git a/xc/doc/specs/Xaw/Xtk.widgets b/xc/doc/specs/Xaw/Xtk.widgets deleted file mode 100644 index d33c240cf..000000000 --- a/xc/doc/specs/Xaw/Xtk.widgets +++ /dev/null @@ -1,5960 +0,0 @@ -\& -.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 -.nr H2 0 -.nr H3 0 -.nr H4 0 -.nr H5 0 -.LP -.XS -Chapter 1 \- Athena Widgets and The Intrinsics -.XE -The Athena widget set and the \*(xI make up the \*(tk. -In the \*(tk, -a widget is the combination of an X window or subwindow -and its associated input and output semantics. -The Athena widgets provide the base functionality necessary to build -a wide variety of application environments. -Because the \*(xI mask implementation details from the widget -and application programmer, -the Athena widgets and the application environments built with them are -fully compatible with the other widget sets built with the \*(xI. -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. -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. -.LP -To the extent possible, -the \*(tk is policy free. -The application environment, not the \*(tk, defines, implements, and enforces: -.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 Library -.LP -.XS -\*(SN Introduction to the \*(tk Library -.XE -The \*(tk library 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 -or add new widgets. -By using the \*(tk library in their applications, -programmers 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 sample interface (widget set) for 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 an application domain, -and others are common across a number of application domains. -.LP -The \*(tk also can implement one or more application interface layers to: -.IP \(bu 5 -Verify the toolkit architecture -.IP \(bu 5 -Provide a base set of widgets and composition policies that -can be incorporated in other application interface layers -.IP \(bu 5 -Make the \*(tk immediately usable by those application -programmers who find that a supplied application interface layer -meets their needs -.LP -The remainder of this chapter discusses the \*(tk: -.IP \(bu 5 -Terminology -.IP \(bu 5 -Model -.IP \(bu 5 -Design principles and philosophy -.LE -.NH 2 -Terminology -.LP -.XS -\*(SN 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 used throughout this book. -.LP -\fBApplication programmer\fP -.IN "Application programmer" "" "@DEF@" -.IP -A programmer who uses the \*(tk to produce an application user interface. -.LP -.PN Child -.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 -.PN "Full\ name" -.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 -The functions or procedures that a widget class implements. -.LP -\fBName\fP -.IN "Name" "" "@DEF@" -.IP -The name that is specific to an instance of a widget for a given client. -.LP -\fBObject\fP -.IN "Object" "" "@DEF@" -.IP -A software 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 as another ``Xt'' function. -.LP -.PN Parent -.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 -.PN Superclass -.IP -A larger class of which a specific class is a member. -All members of a class are also members of the superclass. -.LP -\fBUser\fP -.IN "User" "" "@DEF@" -.IP -A person interacting with a workstation. -.LP -\fBWidget\fP -.IN "Widget" "" "@DEF@" -.IP -An object providing a user-interface abstraction (for example, a Scrollbar -widget). -.LP -\fBWidget class\fP -.IN "Widget class" "" "@DEF@" -.IP -The general group to which a specific widget belongs, -otherwise known as the type of the widget. -.LP -\fBWidget programmer\fP -.IN "Widget programmer" "" "@DEF@" -.IP -A programmer who adds new widgets to the \*(tk. -.NH 2 -Underlying Model -.LP -.XS -\*(SN Underlying Model -.XE -The underlying architectural model is based on the following premises: -.KS -.IP "Widgets are X windows" -.IP -Every user-interface widget is contained in a unique X window. -The X window ID for a widget is readily available from the widget ID, -so standard Xlib window manipulation procedures can operate on -widgets. -.KE -.KS -.IP "Information hiding" -.IP -The data for every widget is private to the widget and its subclasses. -That is, the data is neither directly accessible -nor visible outside of the module implementing the widget. -All program interaction with the widget is performed by a set of operations -(methods) that are defined for the widget. -.KE -.KS -.IP "Widget semantics and widget layout geometry" -.IP -Widget semantics are clearly separated from widget layout -geometry. -Widgets are concerned with implementing specific user-interface -semantics. -They have little control over issues such as their size or -placement relative to other widget peers. -Mechanisms are provided for associating geometric managers with widgets -and for widgets to make suggestions about their own geometry. -.KE -.NH 2 -Design Principles and Philosophy -.LP -.XS -\*(SN Design Principles and Philosophy -.XE -The \*(tk follows two design principles throughout, -which cover languages and language bindings as well as widget IDs. -.NH 3 -Languages and Language Bindings -.LP -The \*(tk facilitates access from objective languages. -However, the \*(tk library is conveniently usable by -application programs written in nonobjective languages. -Procedural interface guidelines are required when the -\*(tk is used with nonobjective languages. -.LP -The guidelines for the procedural interfaces are: -.IP \(bu 5 -Strings are passed as null-terminated character arrays. -.IP \(bu 5 -Most other arrays are passed using two parameters: a size and a pointer to -the first element. -.IP \(bu 5 -Most numeric arguments are passed by value. -.IP \(bu 5 -Structures as arguments are avoided, -unless a method for building them is provided for languages without pointers. -Pointers embedded in structures are allowed, -but they should be avoided if an equivalent alternative is available. -.IP \(bu 5 -Pointers are not recommended as return arguments, unless they will never -have to be dereferenced by the caller. -If they need to be dereferenced, -the caller should allocate storage and pass the address to the procedure -to fill in. -.IP \(bu 5 -Procedures can be passed as parameters. -.IP \(bu 5 -The ownership of dynamically allocated storage is determined on a -case-by-case basis. -The application is also permitted to replace the standard -memory allocation and freeing routines used by the library at build time. -.NH 3 -Widget IDs -.LP -All references to widgets use a unique identifier that is known as the widget ID. -The widget ID is returned to the client by the -.PN XtCreateWidget -function. -From an application programmer's perspective, -a widget ID is an opaque data type; -no particular interpretation can be assigned to it. -Given a widget ID, -you can retrieve the corresponding X window ID, the -.PN Display -and -.PN Screen -structures, and other information by using \*(xI functions. -.LP -From a widget programmer's perspective, -the widget ID actually is a pointer to a data structure -known as the widget instance record. -Several parts of the data structure are common to all widget types, -while other parts are unique to a particular widget type. -The widget's private data that is associated with a particular widget instance -normally is included directly in the widget instance record. -.bp -\& -.sp 1 -.ce 3 -\s+1\fBChapter 2\fP\s-1 - -\s+1\fBUsing Widgets\fP\s-1 -.sp 2 -.nr H1 2 -.nr H2 0 -.nr H3 0 -.nr H4 0 -.nr H5 0 -.LP -.XS -Chapter 2 \- Using Widgets -.XE -Widgets serve as the primary tools for building a user -interface or application environment. -The widget set consists of primitive widgets (for example, a command button) -and composite widgets (for example, a Dialog widget). -.LP -The remaining chapters of this guide explain the widgets and the geometry -managers that work together to provide a set of user-interface components. -These user-interface components serve as a default interface for -application programmers who do not want to implement their own widgets. -In addition, they serve as examples or a starting point -for those widget programmers who, using the \*(xI mechanisms, -want to implement alternative application programming interfaces. -.LP -This chapter discusses the common features of the \*(tk widgets. -.NH 2 -Initializing the Toolkit -.LP -.XS -\*(SN Initializing the Toolkit -.XE -You must invoke the toolkit initialization function -.PN XtInitialize -before invoking any other toolkit routines. -.PN XtInitialize -opens the X server connection, -parses standard parts of the command line, -and creates an initial widget that is to serve as the root of -a tree of widgets that will be created by this application. -.IN "XtInitialize" "" "@DEF@" -.FD 0 -Widget XtInitialize(\fIshell_name\fP, \fIapplication_class\fP, \fIoptions\fP, \ -\fInum_options\fP, \fIargc\fP, \fIargv\fP) -.br - String \fIshell_name\fP; -.br - String \fIapplication_class\fP; -.br - XrmOptionDescRec \fIoptions\fP[]; -.br - Cardinal \fInum_options\fP; -.br - Cardinal *\fIargc\fP; -.br - String \fIargv\fP[]; -.FN -.IP \fIshell_name\fP 1i -Specifies the name of the application shell widget instance, -which usually is something generic like ``main''. -.IP \fIapplication_class\ \ \ \fP 1i -Specifies the class name of this application, -which usually is the generic name for all instances of this application. -By convention, the class name is formed by reversing the case of the -application's first significant letter. -For example, -an application named ``xterm'' would have a class name of ``XTerm''. -.IP \fIoptions\fP 1i -Specifies how to parse the command line for any application-specific resources. -The options argument is passed as a parameter to -.PN XrmParseCommand . -For further information, -see \fI\*(xL\fP. -.IP \fInum_options\fP 1i -Specifies the number of entries in the options list. -.IP \fIargc\fP 1i -Specifies a pointer to the number of command line parameters. -.IP \fIargv\fP 1i -Specifies the command line parameters. -.LP -For further information about this function, -see the \fI\*(xI\fP. -.NH 2 -Creating a Widget -.LP -.XS -\*(SN Creating a Widget -.XE -Creating a widget is a three-step process. -First, the widget instance is allocated, -and various instance-specific attributes are set by using -.PN XtCreateWidget . -Second, the widget's parent is informed of the new child by using -.PN XtManageChild . -Finally, X windows are created for the parent and all its children by using -.PN XtRealizeWidget -and specifying the top-most widget. -The first two steps can be combined by using -.PN XtCreateManagedWidget . -In addition, -.PN XtRealizeWidget -is automatically called when the child becomes managed if the parent -is already realized. -.LP -To allocate and initialize a widget, use -.PN XtCreateWidget . -.IN "XtCreateWidget" "" "@DEF@" -.FD 0 -Widget XtCreateWidget(\fIname\fP, \fIwidget_class\fP, \fIparent\fP, \ -\fIargs\fP, \fInum_args\fP) -.br - String \fIname\fP; -.br - WidgetClass \fIwidget_class\fP; -.br - Widget \fIparent\fP; -.br - ArgList \fIargs\fP; -.br - Cardinal \fInum_args\fP; -.FN -.IP \fIname\fP 1i -Specifies the instance name for the created widget that is used for retrieving -widget resources. -.IP \fIwidget_class\fP 1i -Specifies the widget class pointer for the created widget. -.IP \fIparent\fP 1i -Specifies the parent widget ID. -.IP \fIargs\fP 1i -Specifies the argument list. -The argument list is a variable-length list composed of name -and value pairs that contain information pertaining to the specific widget -instance being created. -For further information, -see Section 2.7.2. -.IP \fInum_args\fP 1i -Specifies the number of arguments in the argument list. -When the num_args is zero, the argument list is never referenced. -.LP -When a widget instance is successfully created, -the widget identifier is returned to the application. -If an error is encountered, -the -.PN XtError -routine is invoked to inform the user of the error. -.LP -For further information, -see the \fI\*(xI\fP. -.NH 2 -Common Arguments in the Widget Argument List -.LP -Although a widget can have unique arguments that it understands, -all widgets have common arguments that provide some regularity of operation. -The common arguments allow arbitrary widgets to be -managed by higher-level components without regards to the individual -widget type. -All widgets ignore any argument that they do not understand. -.LP -The following resources are retrieved from the argument list -or from the resource database by all \*(tk widgets: -.ps 9 -.nr PS 9 -.vs 11 -.nr VS 11 -.TS H -lw(1.5i) lw(1i) lw(1i) lw(2i). -_ -.sp 3p -.TB -Name Type Default Description -.sp 3p -_ -.TH -.R -.sp 3p -XtNbackground Pixel XtDefaultBackground Window background color -XtNbackgroundPixmap Pixmap None Window background pixmap -XtNborderColor Pixel XtDefaultForeground Window border color -XtNborderPixmap Pixmap None Window border pixmap -XtNborderWidth Dimension 1 Width of the border in pixels -T{ -XtNdestroyCallback -T} T{ -XtCallbackList -T} T{ -NULL -T} T{ -Callback for -.PN XtDestroyWidget -T} -XtNheight Dimension Widget dependent Height of the widget -T{ -XtNmappedWhenManaged -T} T{ -Boolean -T} T{ -True -T} T{ -Whether -.PN XtMapWidget -is automatic -T} -XtNsensitive Boolean True Whether widget should receive input -XtNtranslations TranslationTable None Event-to-action translations -XtNwidth Dimension Widget dependent Width of the widget -XtNx Position 0 x coordinate within parent -XtNy Position 0 y coordinate within parent -.sp 3p -_ -.TE -.ps 11 -.nr PS 11 -.vs 13 -.nr VS 13 -.LP -The following additional resources are retrieved from the argument list -or from the resource database by many \*(tk widgets: -.ps 9 -.nr PS 9 -.vs 11 -.nr VS 11 -.TS H -lw(1.5i) lw(1i) lw(1i) lw(2i). -_ -.sp 3p -.TB -Name Type Default Description -.sp 3p -_ -.TH -.R -.sp 3p -XtNcallback XtCallbackList NULL Callback functions and client data -XtNcursor Cursor None Pointer cursor -XtNforeground Pixel XtDefaultForeground Foreground color -.sp 3p -_ -.TE -.ps 11 -.nr PS 11 -.vs 13 -.nr VS 13 -.LP -The value for the XtNcursor resource can be specified in the resource -database as a string, -which can be specified as one of the following: -.IP \(bu 5 -A standard X cursor name from -.Pn < X11/cursorfont.h > -.IP \(bu 5 -FONT font-name glyph-index [[ font-name ] glyph-index ] -.IP \(bu 5 -A relative or absolute file name -.LP -The first font and glyph specify the cursor source pixmap. -The second font and glyph specify the cursor mask pixmap. -The mask font defaults to the source font, -and the mask glyph index defaults to the source glyph index. -.LP -If a relative or absolute file name is specified, -that file is used to create the source pixmap. -Then the string "Mask" is appended to locate the cursor mask pixmap. -If the "Mask" file does not exist, -the suffix "msk" is tried. -If "msk" fails, -no cursor mask will be used. -If a relative file name is used, -the directory specified by the resource name -.PN bitmapFilePath -or class -.PN BitmapFilePath -is added to the beginning of the file name. -If the -.PN bitmapFilePath -resource is not defined, -the default directory on a UNIX-based system is -.PN /usr/include/X11/bitmaps . -.NH 2 -Realizing a Widget -.LP -.XS -\*(SN Realizing a Widget -.XE -The -.PN XtRealizeWidget -function performs two tasks: -.IP \(bu 5 -Creates an X window for the widget and, -if it is a composite widget, for each of its managed children. -.IP \(bu 5 -Maps each window onto the screen. -.IN "XtRealizeWidget" "" "@DEF@" -.FD 0 -void XtRealizeWidget(\fIw\fP) -.br - Widget \fIw\fP; -.FN -.IP \fIw\fP 1i -Specifies the widget. -.LP -For further information about this function, -see the \fI\*(xT\fP. -.NH 2 -Standard Widget Manipulation Functions -.LP -.XS -\*(SN Standard Widget Manipulation Functions -.XE -After a widget has been created, -a client can interact with that widget by calling either of the following: -.IP \(bu 5 -One of the standard widget manipulation routines that -provide functions that all widgets support -.IP \(bu 5 -A widget class-specific manipulation routine -.LP -The \*(tk provides generic routines to provide the -application programmer access to a set of standard widget functions. -These routines let an application or composite widget manipulate -widgets without requiring explicit knowledge of the widget type. -The standard widget manipulation functions let you: -.IP \(bu 5 -Control the location, size and mapping of widget windows -.IP \(bu 5 -Destroy a widget instance -.IP \(bu 5 -Obtain an argument value -.IP \(bu 5 -Set an argument value -.NH 3 -Mapping Widgets -.LP -By default, -widget windows automatically are mapped (made viewable) by -.PN XtRealizeWidget . -This behavior can be changed by using -.PN XtSetMappedWhenManaged , -and it then is the client's responsibility to use the -.PN XtMapWidget -function to make the widget viewable. -.IN "XtSetMappedWhenManaged" "" @DEF@" -.FD 0 -void XtSetMappedWhenManaged(\fIw\fP, \fImap_when_managed\fP) -.br - Widget \fIw\fP; -.br - Boolean \fImap_when_managed\fP; -.FN -.IP \fIw\fP 1i -Specifies the widget. -.IP \fImap_when_managed\fP 1i -Specifies the new value. -If map_when_managed is -.PN True , -the widget is mapped automatically when it is realized. -If map_when_managed is -.PN False , -the client must call -.PN XtMapWidget -or make a second call to -.PN XtSetMappedWhenManaged -to cause the child window to be mapped. -.LP -.sp -The definition for -.PN XtMapWidget -is: -.IN "XtMapWidget" "" "@DEF@" -.FD 0 -XtMapWidget(\fIw\fP) -.br - Widget \fIw\fP; -.FN -.IP \fIw\fP 1i -Specifies the widget. -.LP -When you create several children in sequence for a common parent -after it has been realized, -it is generally more efficient to construct a list of children as -they are created and use -.PN XtManageChildren -to inform their parent of them all at once, -instead of causing each child to be managed separately. -By managing a list of children at one time, -the parent can avoid wasteful duplication of geometry processing -and the associated "screen flash". -.IN "XtManageChildren" "" "@DEF@" -.FD 0 -void XtManageChildren(\fIchildren\fP, \fInum_children\fP) -.br - WidgetList \fIchildren\fP; -.br - Cardinal \fInum_children\fP; -.FN -.IP \fIchildren\fP 1i -Specifies a list of children to add. -.IP \fInum_children\fP 1i -Specifies the number of children to add. -.LP -If the parent is already visible on the screen, -it is especially important to batch updates so that the minimum amount -of visible window reconfiguration is performed. -.LP -For further information about these functions, -see the \fI\*(xI\fP. -.NH 3 -Destroying Widgets -.LP -To destroy a widget instance of any type, use -.PN XtDestroyWidget . -.IN "XtDestroyWidget" "" "@DEF@" -.FD 0 -void XtDestroyWidget(\fIw\fP) -.br - Widget \fIw\fP; -.FN -.IP \fIw\fP 1i -Specifies the widget. -.LP -.PN XtDestroyWidget -destroys the widget and recursively destroys any children that it may have, -including the windows created by its children. -After calling -.PN XtDestroyWidget , -no further references should be made to the widget or to the widget IDs -of any children that the destroyed widget may have had. -.NH 3 -Retrieving Widget Resource Values -.LP -To retrieve the current value of a resource attribute associated -with a widget instance, use -.PN XtGetValues . -.IN "XtGetValues" "" "@DEF@" -.FD 0 -void XtGetValues(\fIw\fP, \fIargs\fP, \fInum_args\fP) -.br - Widget \fIw\fP; -.br - ArgList \fIargs\fP; -.br - Cardinal \fInum_args\fP; -.FN -.IP \fIw\fP 1i -Specifies the widget. -.IP \fIargs\fP 1i -Specifies a variable-length argument list of name and address -pairs that contain the resource name and the address into which the resource value is stored. -.IP \fInum_args\fP 1i -Specifies the number of arguments in the argument list. -.LP -The arguments and values passed in the argument list are dependent on the widget. -Note that the caller is responsible for allocating space into which the returned -resource value is copied; the -.PN ArgList -contains a pointer to this storage. -The caller must allocate storage of the type as represented in the widget. -For example, x and y must be allocated as Position and so on. -For further information, -see the \fI\*(xT\fP. -.NH 3 -Modifying Widget Resource Values -.LP -To modify the current value of a resource attribute associated -with a widget instance, use -.PN XtSetValues . -.IN "XtSetValues" "" "@DEF@" -.FD 0 -void XtSetValues(\fIw\fP, \fIargs\fP, \fInum_args\fP) -.br - Widget \fIw\fP; -.br - ArgList \fIargs\fP; -.br - Cardinal \fInum_args\fP; -.FN -.IP \fIw\fP 1i -Specifies the widget. -.IP \fIargs\fP 1i -Specifies a variable-length argument list of name and value -pairs that contain the arguments to be modified and their new values. -.IP \fInum_args\fP 1i -Specifies the number of arguments in the argument list. -.LP -The arguments and values passed in the argument list depend on -the widget being modified. -Some widgets may not allow certain resources to be modified -after the widget instance has been created or realized. -No notification is given if any part of a -.PN XtSetValues -request is ignored. -.LP -For further information about these functions, -see the \fI\*(xI\fP. -.NT -The argument list entry for -.PN XtGetValues -specifies the address to which the caller wants the value copied. -The argument list entry for -.PN XtSetValues , -however, contains the new value itself if the size of value is less -than sizeof(XtArgVal) (architecture dependent, but at least sizeof(long)); -otherwise, it is a pointer to the value. -String resources are always passed as pointers, regardless of the -length of the string. -.NE -.NH 2 -Using the Client Callback Interface -.LP -.XS -\*(SN Using the Client Callback Interface -.XE -Widgets communicate changes in their state to their clients -by means of a callback facility. -The format for a client's callback handler is: -.IN "CallbackProc" "" "@DEF@" -.FD 0 -void \fICallbackProc\fP(\fIw\fP, \fIclient_data\fP, \fIcall_data\fP) -.br - Widget \fIw\fP; -.br - caddr_t \fIclient_data\fP; -.br - caddr_t \fIcall_data\fP; -.FN -.IP \fIw\fP 1i -Specifies widget for which the callback is registered. -.IP \fIclient_data\fP 1i -Specifies arbitrary client-supplied data that the widget should pass back -to the client when the widget executes the client's callback procedure. -This is a way for the client registering the callback to also register -client-specific data: -a pointer to additional information about the widget, -a reason for invoking the callback, and so on. -It is perfectly normal to have client_data of NULL -if all necessary information is in the widget. -This field is also frequently known as the \fIclosure\fP. -.IP \fIcall_data\fP 1i -Specifies any callback-specific data the widget wants to pass to the client. -For example, when Scrollbar executes its jumpProc callback list, -it passes the current position of the thumb in the call_data argument. -.LP -Callbacks can be registered with widgets in one of two ways. -When the widget is created, -a pointer to a list of callback procedure and data pairs can be passed in the -argument list to -.PN XtCreateWidget . -The list is of type -.PN XtCallbackList : -.IN "XtCallbackProc" -.IN "XtCallbackList" "" "@DEF@" -.LP -.Ds 0 -.TA .5i 3i -.ta .5i 3i -typedef struct { - XtCallbackProc callback; - caddr_t closure; -} XtCallbackRec, *XtCallbackList; -.De -.LP -The callback list must be allocated and initialized before calling -.PN XtCreateWidget . -The end of the list is identified by an entry containing NULL in -callback and closure. -Once the widget is created, -the client can change or de-allocate this list; -The widget itself makes no further reference to it. -The closure field contains the client_data passed to the callback -when the callback list is executed. -.LP -The second method for registering callbacks is to use -.PN XtAddCallback -after the widget has been created. -.IN "XtAddCallback" "" "@DEF@" -.FD 0 -void XtAddCallback(\fIw\fP, \fIcallback_name, \fP\fIcallback\fP, \ -\fIclient_data\fP) -.br - Widget \fIw\fP; -.br - String \fIcallback_name\fP; -.br - XtCallbackProc \fIcallback\fP; -.br - caddr_t \fIclient_data\fP; -.FN -.IP \fIw\fP 1i -Specifies the widget to add the callback to. -.IP \fIcallback_name\fP 1i -Specifies the callback list within the widget to append to. -.IP \fIcallback\fP 1i -Specifies the callback procedure to add. -.IP \fIclient_data\fP 1i -Specifies the data to be passed to the callback when it is invoked. -.LP -.PN XtAddCallback -adds the specified callback to the list for the named widget. -.LP -All widgets provide a callback list named -.PN XtNdestroyCallback -where clients can register procedures that are to be executed when the widget -is destroyed. -The destroy callbacks are executed when the widget or an ancestor is destroyed. -The call_data argument is unused for destroy callbacks. -.LP -The \*(tk \*(xI provide additional functions for further manipulating -a callback list. -For information about these functions, see -.PN XtCallCallbacks , -.PN XtRemoveCallback , -.PN XtRemoveCallbacks , -and -.PN XtRemoveAllCallbacks -in the \fI\*(xT\fP. -.NH 2 -Programming Considerations -.LP -.XS -\*(SN Programming Considerations -.XE -This section provides some guidelines to set up an application -program that uses the \*(tk. -This section discusses: -.IP \(bu 5 -Writing applications -.IP \(bu 5 -Creating argument lists -.NH 3 -Writing Applications -.LP -When writing an application that uses the toolkit, -you should make sure that your application performs the following: -.IP 1. 5 -Include -.Pn < X11/Intrinsic.h > -in your application programs. -This header file automatically includes -.Pn < X11/Xlib.h >, -so all Xlib functions also are defined. -.IP 2. 5 -Include the widget-specific header files for each widget type -that you need to use. -For example, -.Pn < X11/Label.h > -and -.Pn < X11/Command.h >. -.IP 3. 5 -Call the -.PN XtInitialize -function before invoking any other toolkit or Xlib functions. -For further information, -see Section 2.1 and the \fI\*(xT\fP. -.IP 4. 5 -To pass attributes to the widget creation routines -that will over-ride any site or user customizations, -set up argument lists. -In this document, -a list of valid argument names that start with -.PN XtN -is provided in the discussion of each widget. -.IP -For further information, -see Section 2.7.2. -.IP 5. 5 -When the argument list is set up, -create the widget by using the -.PN XtCreateWidget -function. -For further information, -see Section 2.2 and the \fI\*(xT\fP. -.IP 6. 5 -If the widget has any callback routines, which are usually defined by the -.PN XtNcallback -argument or the -.PN XtAddCallback -function, declare these routines within the application. -.IP 7. 5 -After a widget has been created, use -.PN XtManageChild -to manage it. -If there is no manipulation of the widget between -.PN XtCreateWidget -and -.PN XtManageChild, -you can do this in a single step by using -.PN XtCreateManagedWidget . -For further information about these functions, -see the \fI\*(xI\fP. -.IP 8. 5 -After creating the initial widget hierarchy, windows must be created -for each widget by calling -.PN XtRealizeWidget -on the top level widget. -.IP 9. 5 -Most applications now sit in a loop processing events using -.PN XtMainLoop , -for example: -.IP -.Ds 0 -XtCreateManagedWidget(\fIname\fP, \fIclass\fP, \fIparent\fP, \fIargs\fP, \fInum_args\fP); -XtRealizeWidget(\fIparent\fP); -XtMainLoop(\|); -.De -.IP -For information about this function, -see the \fI\*(xT\fP. -.IP 10. 5 -Link your application with -.PN libXaw.a -(the Athena widgets), -.PN libXmu.a -(miscellaneous utilities), -.PN libXt.a -(the \*(tk \*(xI), and -.PN libX11.a -(the core X library). -The following provides a sample command line: -.IP -.Ds 0 -cc -o \fIapplication\fP \fIapplication\fP.c \-lXaw \-lXmu \-lXt \-lX11 -.De -.NH 3 -Creating Argument Lists -.LP -To set up an argument list for the inline specification of widget attributes, -you can use one of the four approaches discussed in this section. -You should use whichever approach fits the needs of the application -and you are most comfortable with. -In general, -argument lists should be kept as short as possible to allow widget attributes -to be specified through the resource database. -Whenever a client inserts a specific attribute value in an argument list, -the user is prevented from customizing the behavior of the widget. -Resource names in the resource database, by convention, -correspond to their symbolic names that are used in argument list without the -.PN XtN -prefix. -For example, the resource name for -.PN XtNforeground -is ``foreground''. -For further information, -see the \fI\*(xI\fP. -.LP -The -.PN Arg -structure contains: -.IN "ArgList" "" "@DEF@" -.IN "Arg" "" "@DEF@" -.LP -.Ds 0 -.TA .5i 1.5i -.ta .5i 1.5i -typedef struct { - String name; - XtArgVal value; -} Arg, *ArgList; -.De -.LP -The first approach lets you statically initialize the argument list. -For example: -.LP -.Ds 0 -.TA .5i -.ta .5i -static Arg arglist[] = { - {XtNwidth, (XtArgVal) 400}, - {XtNheight, (XtArgVal) 300}, -}; -.De -.LP -This approach makes it easy to add or delete new -elements. -The -.PN XtNumber -macro can be used to compute the number of elements in the argument list, -thus preventing simple programming errors. -The following provides an example: -.LP -.Ds -XtCreateWidget(\fIname\fP, \fIclass\fP, \fIparent\fP, \fIarglist\fP, XtNumber(\fIarglist\fP)); -.De -.LP -The second approach lets you use the -.PN XtSetArg -macro. -For example: -.LP -.Ds 0 -.TA .5i -.ta .5i -Arg arglist[10]; -XtSetArg(arglist[1], XtNwidth, 400); -XtSetArg(arglist[2], XtNheight, 300); -.De -.LP -To make it easier to insert and delete entries, -you also can use a variable index, -as in this example: -.LP -.Ds 0 -.TA .5i -.ta .5i -Arg arglist[10]; -Cardinal i=0; -XtSetArg(arglist[i], XtNwidth, 400); i++; -XtSetArg(arglist[i], XtNheight, 300); i++; -.De -.LP -The i variable can then be used as the argument list count in the widget -create function. -In this example, -.PN XtNumber -would return 10, not 2, and therefore is not useful. -.NT -You should not use auto-increment or auto-decrement -within the first argument to -.PN XtSetArg . -As it is currently implemented, -.PN XtSetArg -is a macro that dereferences the first argument twice. -.NE -.LP -The third approach lets you individually set the elements of the argument list array, -one piece at a time. -For example: -.LP -.Ds 0 -.TA .5i -.ta .5i -Arg arglist[10]; -arglist[0].name = XtNwidth; -arglist[0].value = (XtArgVal) 400; -arglist[1].name = XtNheight; -arglist[1].value = (XtArgVal) 300; -.De -.LP -Note that in this example, as in the previous example, -.PN XtNumber -would return 10, not 2, and therefore is not useful. -.LP -The fourth approach lets you use a mixture of the first and third approaches: -you can statically define the argument list but modify some entries at runtime. -For example: -.LP -.Ds 0 -.TA .5i -.ta .5i -static Arg arglist[] = { - {XtNwidth, (XtArgVal) 400}, - {XtNheight, (XtArgVal) NULL}, -}; -arglist[1].value = (XtArgVal) 300; -.De -.LP -In this example, -.PN XtNumber -can be used, as in the first approach, for easier code maintenance. -.NH 3 -Sample Program -.LP -The following program creates one command button that, when pressed, -causes the program to exit. -This example is a complete program that illustrates: -.IP \(bu 5 -Toolkit initialization -.IP \(bu 5 -Optional command-line arguments -.IP \(bu 5 -Widget creation -.IP \(bu 5 -Callback routines -.LP -.bp -.ps 9 -.nr PS 9 -.Ds 0 -.TA .5i 2i -.ta .5i 2i -#include <stdio.h> -#include <X11/Intrinsic.h> -#include <X11/Command.h> -.sp 6p -static XrmOptionDescRec options[] = { -{"\-label", "*button.label", XrmoptionSepArg, NULL} -}; -.sp 6p -Syntax(call) - char *call; -{ - fprintf(stderr, "Usage: %s\\n", call); -} -.sp 6p -void Activate(w, client_data, call_data) - Widget w; - caddr_t client_data; /* unused */ - caddr_t call_data; /* unused */ -{ - printf("button was activated.\\n"); - exit(0); -} -.sp 6p -void main(argc, argv) - unsigned int argc; - char **argv; -{ - Widget toplevel; - static XtCallbackRec callbacks[] = { - \ \ \ \ { Activate, NULL }, - \ \ \ \ { NULL, NULL }, - }; -.sp 6p - static Arg args[] = { - \ \ { XtNcallback, (XtArgVal)callbacks }, - }; -.sp 6p - toplevel = XtInitialize("main", "Demo", options, XtNumber(options), &argc, argv ); - if (argc != 1) Syntax(argv[0]); -.sp 6p - XtCreateManagedWidget("button",commandWidgetClass,toplevel,args,XtNumber(args)); -.sp 6p - XtRealizeWidget(toplevel); - XtMainLoop(\|); -} -.De -.ps 11 -.nr PS 11 -.bp -\& -.sp 1 -.ce 3 -\s+1\fBChapter 3\fP\s-1 - -\s+1\fBAthena Widget Set\fP\s-1 -.sp 2 -.nr H1 3 -.nr H2 0 -.nr H3 0 -.nr H4 0 -.nr H5 0 -.na -.LP -.XS -Chapter 3 - Athena Widget Set -.XE -.LP -This chapter describes the following Athena widgets: -.IP \(bu 5 -Command -.IP \(bu 5 -Label -.IP \(bu 5 -Text -.IP \(bu 5 -Scrollbar -.IP \(bu 5 -Viewport -.IP \(bu 5 -Box -.\".IP \(bu 5 -.\"MenuBox -.IP \(bu 5 -VPaned -.IP \(bu 5 -Form -.IP \(bu 5 -Dialog -.IP \(bu 5 -List -.IP \(bu 5 -Grip -.IP \(bu 5 -Toggle -.LE -.NH 2 -Command Widget -.LP -.XS -\*(SN Command Widget -.XE -.IN "Command widget" "" "@DEF@" -The Command widget is a rectangular button that contains a text or -pixmap label. -When the pointer cursor is on the button, -the button border is highlighted to indicate that the button is available -for selection. -Then, when a pointer button is pressed and released -the button is selected, -and the application's callback routine is invoked. -.LP -The class variable for the Command widget is -.PN commandWidgetClass . -.LP -When creating a Command widget instance, -the following resources are retrieved from the argument list -or from the resource database: -.IN "Command widget" "resources" -.ps 9 -.nr PS 9 -.vs 11 -.nr VS 11 -.TS H -lw(1.5i) lw(1i) lw(1i) lw(2i). -_ -.sp 3p -.TB -Name Type Default Description -.sp 3p -_ -.TH -.R -.sp 3p -XtNbackground Pixel XtDefaultBackground Window background color -XtNbackgroundPixmap Pixmap None Window background pixmap -T{ -XtNbitmap -T} T{ -Pixmap -T} T{ -None -T} T{ -Pixmap to display in place of the label -T} -XtNborderColor Pixel XtDefaultForeground Window border color -XtNborderPixmap Pixmap None Window border pixmap -XtNborderWidth Dimension 1 Width of button border -XtNcallback XtCallbackList NULL Callback for button select -XtNcursor Cursor None Pointer cursor -T{ -XtNdestroyCallback -T} T{ -XtCallbackList -T} T{ -NULL -T} T{ -Callbacks for -.PN XtDestroyWidget -T} -XtNfont XFontStruct* XtDefaultFont Label font -XtNforeground Pixel XtDefaultForeground Foreground color -XtNheight Dimension Text height Button height -T{ -XtNhighlightThickness -T} T{ -Dimension -T} T{ -2 -T} T{ -Width of border to be highlighted -T} -XtNinsensitiveBorder Pixmap Gray Border when not sensitive -T{ -XtNinternalHeight -T} T{ -Dimension -T} T{ -2 -T} T{ -Internal border height for highlighting -T} -T{ -XtNinternalWidth -T} T{ -Dimension -T} T{ -4 -T} T{ -Internal border width for highlighting -T} -XtNjustify XtJustify XtJustifyCenter Type of text alignment -XtNlabel String Button name Button label -T{ -XtNmappedWhenManaged -T} T{ -Boolean -T} T{ -True -T} T{ -Whether -.PN XtMapWidget -is automatic -T} -XtNresize Boolean True Whether to auto-resize in SetValues -XtNsensitive Boolean True Whether widget receives input -XtNtranslations TranslationTable see below Event-to-action translations -XtNwidth Dimension Text width Button width -XtNx Position 0 x coordinate -XtNy Position 0 y coordinate -.sp 3p -_ -.TE -.ps 11 -.nr PS 11 -.vs 13 -.nr VS 13 -.LP -The new resources associated with the Command widget are: -.TS -lw(1.5i) lw(4i). -T{ -.PN XtNbitmap -T} T{ -Specifies a bitmap to display in place of the text label. -See the description of this resource in the Label widget for -further details. -T} -.sp 6p -T{ -.PN XtNheight -T} T{ -Specifies the height of the Command widget. -The default value is the minimum height that will contain: -.br -XtNinternalheight + height of XtNlabel + XtNinternalHeight -.br -If the specified height is larger than the minimum, -the label string is centered vertically. -T} -.sp 6p -T{ -.PN XtNinternalHeight -T} T{ -Represents the distance in pixels between the top and bottom -of the label text or bitmap and the horizontal edges of the Command widget. -HighlightThickness can be larger or smaller than this value. -T} -.sp 6p -T{ -.PN XtNinternalWidth -T} T{ -Represents the distance in pixels between the ends of the label text -or bitmap and the vertical edges of the Command widget. -HighlightThickness can be larger or smaller than this value. -T} -.sp 6p -T{ -.PN XtNjustify -T} T{ -Specifies left, center, or right alignment of the label string -within the Command widget. -If it is specified within an -.PN ArgList , -one of the values -.PN XtJustifyLeft , -.PN XtJustifyCenter , -or -.PN XtJustifyRight -can be specified. -In a resource of type ``string'', -one of the values ``left'', ``center'', or ``right'' can be specified. -T} -.sp 6p -T{ -.PN XtNlabel -T} T{ -Specifies the text string that is to be displayed in the Command widget -if no bitmap is specified. -The default is the widget name of the Command widget. -T} -.sp 6p -T{ -.PN XtNresize -T} T{ -Specifies whether the Command widget should attempt to resize to its -preferred dimensions whenever -.PN XtSetValues -is called for it. -The default is -.PN True . -T} -.sp 6p -T{ -.PN XtNsensitive -T} T{ -If set to -.PN False , -the Command widget will change its window border to -.PN XtNinsensitiveBorder -and will stipple the label string. -T} -.sp 6p -T{ -.PN XtNwidth -T} T{ -Specifies the width of the Command widget. -The default value is the minimum width that will contain: -.br -XtNinternalWidth + width of XtNlabel + XtNinternalWidth -.br -If the width is larger or smaller than the minimum, -.PN XtNjustify -determines how the label string is aligned. -T} -.TE -.LP -The Command widget supports the following actions: -.IP \(bu 5 -Switching the button between the foreground and background -colors with \fBset\fP and \fBunset\fP -.IP \(bu 5 -Processing application callbacks with \fBnotify\fP -.IP \(bu 5 -Switching the internal border between highlighted -and unhighlighted states with \fBhighlight\fP and \fBunhighlight\fP -.LE -.LP -The following are the default translation bindings that are used -by the Command widget: -.LP -.Ds 0 -.TA .5i 2.25i -.ta .5i 2.25i - <EnterWindow>: highlight(\|) - <LeaveWindow>: reset(\|) - <Btn1Down>: set(\|) - <Btn1Up>: notify(\|) unset(\|) -.De -.LP -With these bindings, the user can cancel the action before -releasing the button by moving the pointer out of the Command widget. -.NH 3 -Command Actions -.LP -The full list of actions supported by Command is: -.IP \fBhighlight\fP(\fIcondition\fP) 1.5i -Displays the internal highlight border in the color (\fBXtNforeground\fP -or -.PN XtNbackground ) -that contrasts with the interior color of the Command widget. -This action procedure takes one of the following conditions: WhenUnset and -Always. If no argument is passed then WhenUnset is assumed, this maintains -backwards compatibility. -.IP \fBunhighlight\fP(\|) 1.5i -Displays the internal highlight border in the color (\fBXtNforeground\fP -or -.PN XtNbackground ) -that matches the interior color of the Command widget. -.IP \fBset\fP(\|) 1.5i -Enters the "set" state, in which \fBnotify\fP is possible and displays the -interior of the button in the -.PN XtNforeground -color. The label is displayed -in the -.PN XtNbackground -color. -.IP \fBunset\fP(\|) 1.5i -Cancels the "set" state and displays the interior of the button in the -.PN XtNbackground -color. The label is displayed in the -.PN XtNforeground -color. -.IP \fBreset\fP(\|) 1.5i -Cancels any \fBset\fP or \fBhighlight\fP and displays the interior of the -button in the -.PN XtNbackground -color, with the label displayed in the -.PN XtNforeground -color. -.IP \fBnotify\fP(\|) 1.5i -Executes the -.PN XtNcallback -callback list if executed in the \fBset\fP state. The value of the call_data -argument is undefined. -.LP -.IN "Command widget" "creating" -.IN "Creating widgets" "Command" -To create a Command widget instance, use -.PN XtCreateWidget -and specify the class variable -.PN commandWidgetClass . -.LP -.IN "Command widget" "destroying" -.IN "Destroying widgets" "Command" -To destroy a Command widget instance, use -.PN XtDestroyWidget -and specify the widget ID of the button. -.LP -The Command widget supports two callback lists: -.PN XtNdestroyCallback -and -.PN XtNcallback . -The notify action executes the callbacks on the -.PN XtNcallback -list. -The call_data -argument is unused. -.NH 2 -Label Widget -.LP -.XS -\*(SN Label Widget -.XE -.IN "Label widget" "" "@DEF@" -A Label is an noneditable text string or pixmap that is displayed within a window. -The string is limited to one line and can be aligned to the left, right, -or center of its window. -A Label can neither be selected nor directly edited by the user. -.LP -The class variable for the Label widget is -.PN labelWidgetClass . -.LP -When creating a Label widget instance, -the following resources are retrieved from the argument list -or from the resource database: -.IN "Label widget" "resources" -.ps 9 -.nr PS 9 -.vs 11 -.nr VS 11 -.TS H -lw(1.5i) lw(1i) lw(1i) lw(2i). -_ -.sp 3p -.TB -Name Type Default Description -.sp 3p -_ -.TH -.R -.sp 3p -XtNbackground Pixel XtDefaultBackground Window background color -XtNbackgroundPixmap Pixmap None Window background pixmap -T{ -XtNbitmap -T} T{ -Pixmap -T} T{ -None -T} T{ -Pixmap to display in place of the label -T} -XtNborderColor Pixel XtDefaultForeground Window border color -XtNborderPixmap Pixmap None Window border pixmap -XtNborderWidth Dimension 1 Border width in pixels -XtNcursor Cursor None Pointer cursor -T{ -XtNdestroyCallback -T} T{ -XtCallbackList -T} T{ -NULL -T} T{ -Callbacks for -.PN XtDestroyWidget -T} -XtNfont XFontStruct* XtDefaultFont Label font -XtNforeground Pixel XtDefaultForeground Foreground color -XtNheight Dimension text height Height of widget -XtNinsensitiveBorder Pixmap Gray Border when not sensitive -XtNinternalHeight Dimension 2 See note -XtNinternalWidth Dimension 4 See note -XtNjustify XtJustify XtJustifyCenter Type of text alignment -XtNlabel String label name String to be displayed -T{ -XtNmappedWhenManaged -T} T{ -Boolean -T} T{ -True -T} T{ -Whether -.PN XtMapWidget -is automatic -T} -XtNresize Boolean True Whether to auto-resize in SetValues -XtNsensitive Boolean True Whether widget receives input -XtNwidth Dimension text width Width of widget -XtNx Position 0 x coordinate in pixels -XtNy Position 0 y coordinate in pixels -.sp 3p -_ -.TE -.ps 11 -.nr PS 11 -.vs 13 -.nr VS 13 -.LP -The new resources associated with Label are: -.TS -lw(1.5i) lw(4i). -T{ -.PN XtNbitmap -T} T{ -Specifies a bitmap to display in place of the text label. -The bitmap can be specified as a string in the resource data base. -The StringToPixmap converter will interpret the string as the name of a -file in the bitmap utility format that is to be loaded into a pixmap. -The string can be an absolute or a relative file name. -If a relative file name is used, -the directory specified by the resource name -.PN bitmapFilePath -or -the resource class -.PN BitmapFilePath -is add to the beginning of the -specified file name. -If the -.PN bitmapFilePath -resource is not defined, -the default directory on a UNIX-based system is -.PN /usr/include/X11/bitmaps . -T} -.sp 6p -T{ -.PN XtNheight -T} T{ -Specifies the height of the Label widget. -The default value is the minimum height that will contain: -.br -XtNinternalheight + height of XtNlabel + XtNinternalHeight -.br -If the specified height is larger than the minimum, -the label string is centered vertically. -T} -.sp 6p -T{ -.PN XtNinternalHeight -T} T{ -Represents the distance in pixels between the top and bottom -of the label text or bitmap and the horizontal edges of the Label widget. -T} -.sp 6p -T{ -.PN XtNinternalWidth -T} T{ -Represents the distance in pixels between the ends of the label text or bitmap -and the vertical edges of the Label widget. -T} -.sp 6p -T{ -.PN XtNjustify -T} T{ -Specifies left, center, or right alignment of the label string -within the Label widget. -If it is specified within an -.PN ArgList , -one of the values -.PN XtJustifyLeft , -.PN XtJustifyCenter , -or -.PN XtJustifyRight -can be specified. -In a resource of type ``string'', -one of the values ``left'', ``center'', or ``right'' can be specified. -T} -.sp 6p -T{ -.PN XtNlabel -T} T{ -Specifies the text string that is to be displayed in the button -if no bitmap is specified. -The default is the widget name of the Label widget. -T} -.sp 6p -T{ -.PN XtNresize -T} T{ -Specifies whether the Label widget should attempt to resize to its -preferred dimensions whenever -.PN XtSetValues -is called for it. -T} -.sp 6p -T{ -.PN XtNsensitive -T} T{ -If set to -.PN False , -the Label widget will change its window border to -.PN XtNinsensitiveBorder -and will stipple the label string. -T} -.sp 6p -T{ -.PN XtNwidth -T} T{ -Specifies the width of the Label widget. -The default value is the minimum width that will contain: -.br -XtNinternalWidth + width of XtNlabel + XtNinternalWidth -.br -If the width is larger or smaller than the minimum, -.PN XtNjustify -determines how the label string is aligned. -T} -.TE -.LP -.IN "Label widget" "creating" -.IN "Creating widgets" "Label" -To create a Label widget instance, use -.PN XtCreateWidget -and specify the class variable -.PN labelWidgetClass . -.LP -.IN "Label widget" "destroying" -.IN "Destroying widgets" "Label" -To destroy a Label widget instance, use -.PN XtDestroyWidget -and specify the widget ID of the label. -.LP -The Label widget supports only the -.PN XtNdestroyCallback -callback list. -.NH 2 -Text Widget -.LP -.XS -\*(SN Text Widget -.XE -.IN "Text widget" "" "@DEF@" -A Text widget is a window that provides a way for an application to display -one or more lines of text. -The displayed text can reside in a file on disk or in a string in memory. -An option also lets an application display a vertical Scrollbar -in the Text window, -letting the user scroll through the displayed text. -Other options allow an application to let the user modify the text -in the window. -.LP -The Text widget is divided into three parts: -.IP \(bu 5 -Source -.IP \(bu 5 -Sink -.IP \(bu 5 -Text widget -.LP -The idea is to separate the storage -of the text (source) from the painting of the text (sink). -The Text widget coordinates the sources and sinks. -Clients usually will use -.PN AsciiText -widgets that automatically create the source and sink for the client. -A client can, if it so chooses, explicitly create the source and sink -before creating the Text widget. -.LP -The source stores and manipulates the text. -The \*(tk provides string and disk file sources. -The source determines what editing functions may be performed on the text. -.LP -The sink obtains the fonts and the -colors in which to paint the text. -The sink also computes what text can fit on each line. -The \*(tk provides a single-font, single-color ASCII sink. -.LP -If a disk file is used to display the text, -two edit modes are available: -.IP \(bu 5 -Append -.IP \(bu 5 -Read-only -.LP -Append mode lets the user enter text into the window, -while read-only mode does not. -Text may only be entered if the insertion point is after the last -character in the window. -.LP -If a string in memory is used, -the application must allocate the amount of space needed. -If a string in memory is used to display text, -three types of edit mode are available: -.IN "Text widget" "edit modes" -.IP \(bu 5 -Append-only -.IP \(bu 5 -Read-only -.IP \(bu 5 -Editable -.LP -The first two modes are the same as displaying text from a disk file. -Editable mode lets the user place the cursor anywhere in the text and -modify the text at that position. -The text cursor position can be modified by using the -key strokes or pointer buttons defined by the event bindings. -.LE -Many standard keyboard editing facilities are supported by the -event bindings. -The following actions are supported: -.LP -.Ds 0 -.TA .5i 2.5i 3i -.ta .5i 2.5i 3i -Cursor Movement Delete - forward-character delete-next-character - backward-character delete-previous-character - forward-word delete-next-word - backward-word delete-previous-word - forward-paragraph delete-selection - backward-paragraph - beginning-of-line - end-of-line Selection - next-line select-word - previous-line select-all - next-page select-start - previous-page select-adjust - beginning-of-file select-end - end-of-file extend-start - scroll-one-line-up extend-adjust - scroll-one-line-down extend-end - -New Line Miscellaneous - newline-and-indent redraw-display - newline-and-backup insert-file - newline insert-char - insert-string - display-caret - do-nothing - -Kill Unkill - kill-word unkill - backward-kill-word stuff - kill-selection insert-selection - kill-to-end-of-line - kill-to-end-of-paragraph -.De -.NT Notes -.IP 1. 5 -A page corresponds to the size of the Text window. -For example, if the Text window is 50 lines in length, -scrolling forward one page is the same as scrolling forward 50 lines. -.IP 2. 5 -The \fBinsert-char\fP action may only be attached to a key event. It -calls XLookupString to translate the event into a (rebindable) Latin-1 -character (sequence) and inserts that sequence into the text at the -current position. The \fBinsert-string\fP action takes one or more -arguments and inserts the arguments into the text at the current position. -An argument beginning with the characters "0x" and containing only -valid hexadecimal digits in the remainder is interpreted as a hexadecimal -constant and the corresponding single character is inserted instead. -.IP 3. 5 -The \fBdelete\fP -action deletes a text item. -The \fBkill\fP -action deletes a text item and puts the item in the kill buffer -(X cut buffer 1). -.IP 4. 5 -The \fBunkill\fP -action inserts the contents of the kill buffer into the text at the current -position. -The \fBstuff\fP -action inserts the contents of the paste buffer (X cut buffer 0) into the -text at the current position. -The \fBinsert-selection\fP -action retrieves the value of a specified X selection or cut -buffer, with fall-back to alternative selections or cut buffers. -.IP 5. 5 -The \fBdisplay-caret\fP -action allows the insert position marker to be turned on and off. -The first argument specifies the desired state as any of the string -values accepted for Boolean resources (e.g. "on", "true", "off", "false", -etc.). If no arguments are specified, the default value is "on". -The second argument specifies, for -.PN EnterNotify or -.PN LeaveNotify -events whether or not the focus field in the event is to be examined. -If the second argument is not specified, or specified as something other -than "always" then if the action is bound to an -.PN EnterNotify or -.PN LeaveNotify -event, the action will be taken only if the focus field is \fBTrue\fP. -An augmented binding that might be useful is: -.LP -.Ds 0 -.TA .5i 2.25i -.ta .5i 2.25i -*Text.Translations: #override \\ - <FocusIn>: display-caret(on) \\n\\ - <FocusOut>: display-caret(off) -.De -.NE -.LP -The default event bindings for the Text widget are: -.IN "Text widget" "default bindings" -.LP -.Ds 0 -.TA .5i 2.5i -.ta .5i 2.5i -char defaultTextTranslations[] = ``\\ - Ctrl<Key>F: forward-character(\|) \\n\\ - Ctrl<Key>B: backward-character(\|) \\n\\ - Ctrl<Key>D: delete-next-character(\|) \\n\\ - Ctrl<Key>A: beginning-of-line(\|) \\n\\ - Ctrl<Key>E: end-of-line(\|) \\n\\ - Ctrl<Key>H: delete-previous-character(\|) \\n\\ - Ctrl<Key>J: newline-and-indent(\|) \\n\\ - Ctrl<Key>K: kill-to-end-of-line(\|) \\n\\ - Ctrl<Key>L: redraw-display(\|) \\n\\ - Ctrl<Key>M: newline(\|) \\n\\ - Ctrl<Key>N: next-line(\|) \\n\\ - Ctrl<Key>O: newline-and-backup(\|) \\n\\ - Ctrl<Key>P: previous-line(\|) \\n\\ - Ctrl<Key>V: next-page(\|) \\n\\ - Ctrl<Key>W: kill-selection(\|) \\n\\ - Ctrl<Key>Y: unkill(\|) \\n\\ - Ctrl<Key>Z: scroll-one-line-up(\|) \\n\\ - Meta<Key>F: forward-word(\|) \\n\\ - Meta<Key>B: backward-word(\|) \\n\\ - Meta<Key>I: insert-file(\|) \\n\\ - Meta<Key>K: kill-to-end-of-paragraph(\|) \\n\\ - Meta<Key>V: previous-page(\|) \\n\\ - Meta<Key>Y: stuff(\|) \\n\\ - Meta<Key>Z: scroll-one-line-down(\|) \\n\\ - :Meta<Key>d: delete-next-word(\|) \\n\\ - :Meta<Key>D: kill-word(\|) \\n\\ - :Meta<Key>h: delete-previous-word(\|) \\n\\ - :Meta<Key>H: backward-kill-word(\|) \\n\\ - :Meta<Key>\\<: beginning-of-file(\|) \\n\\ - :Meta<Key>\\>: end-of-file(\|) \\n\\ - :Meta<Key>]: forward-paragraph(\|) \\n\\ - :Meta<Key>[: backward-paragraph(\|) \\n\\ - ~Shift Meta<Key>Delete: delete-previous-word(\|) \\n\\ - \ Shift Meta<Key>Delete: backward-kill-word(\|) \\n\\ - ~Shift Meta<Key>Backspace: delete-previous-word(\|) \\n\\ - \ Shift Meta<Key>Backspace: backward-kill-word(\|) \\n\\ - <Key>Right: forward-character(\|) \\n\\ - <Key>Left: backward-character(\|) \\n\\ - <Key>Down: next-line(\|) \\n\\ - <Key>Up: previous-line(\|) \\n\\ - <Key>Delete: delete-previous-character(\|) \\n\\ - <Key>BackSpace: delete-previous-character(\|) \\n\\ - <Key>Linefeed: newline-and-indent(\|) \\n\\ - <Key>Return: newline(\|) \\n\\ - <Key>: insert-char(\|) \\n\\ - <FocusIn>: focus-in(\|) \\n\\ - <FocusOut>: focus-out(\|) \\n\\ - <Btn1Down>: select-start(\|) \\n\\ - <Btn1Motion>: extend-adjust(\|) \\n\\ - <Btn1Up>: extend-end(PRIMARY, CUT_BUFFER0) \\n\\ - <Btn2Down>: insert-selection(PRIMARY, CUT_BUFFER0) \\n\\ - <Btn3Down>: extend-start(\|) \\n\\ - <Btn3Motion>: extend-adjust(\|) \\n\\ - <Btn3Up>: extend-end(PRIMARY, CUT_BUFFER0) \\ -''; -.De -.LP -A user-supplied resource entry can use application-specific bindings, a subset -of the supplied default bindings, or both. -The following is an example of a user-supplied resource entry that uses a -subset of the default bindings: -.LP -.Ds 0 -.TA .5i 1.75i -.ta .5i 1.75i -Xmh*Text.Translations: \\ - <Key>Right: forward-character(\|) \\n\\ - <Key>Left: backward-character(\|) \\n\\ - Meta<Key>F: forward-word(\|) \\n\\ - Meta<Key>B: backward-word(\|) \\n\\ - :Meta<Key>]: forward-paragraph(\|) \\n\\ - :Meta<Key>[: backward-paragraph(\|) \\n\\ - <Key>: insert-char(\|) -.De -.LP -An augmented binding that is useful with the xclipboard -utility is: -.LP -.Ds 0 -.TA .5i 2.25i -.ta .5i 2.25i -*Text.Translations: #override \\ - Button1 <Btn2Down>: extend-end(CLIPBOARD) -.De -.LP -A Text widget lets both the user and the application -take control of the text being displayed. -The user takes control with the scroll bar or with key strokes -defined by the event bindings. -The scroll bar option places the scroll bar on the left side of the widget -and can be used with any editing mode. -The application takes control with procedure calls to the Text widget -to: -.IP \(bu 5 -Display text at a specified position -.IP \(bu 5 -Highlight specified text areas -.IP \(bu 5 -Replace specified text areas -.LE -.LP -The text that is selected within a Text widget may be assigned to an -X selection or copied into a cut buffer -and can be retrieved by the application with the Intrinsics -.PN XtGetSelectionValue -or the Xlib -.PN XFetchBytes -functions respectively. -Several standard selection schemes -(e.g. character/word/paragraph with multi-click) -are supported through the event bindings. -.LP -The class variable for the Text widget is -.PN textWidgetClass . -.LP -.IN "Text widget" "creating" -.IN "Creating widgets" "Text string" -To create a Text string widget, use -.PN XtCreateWidget -and specify the class variable -.PN asciiStringWidgetClass . -.LP -.IN "Creating widgets" "Text file" -To create a Text file widget, use -.PN XtCreateWidget -and specify the class variable -.PN asciiDiskWidgetClass . -.NT -If you want to create an instance of the class -.PN textWidgetClass , -you must provide a source and a sink when the widget is created. -The Text widget cannot be instantiated without both. -.NE -.LP -When creating a Text widget instance, -the following resources are retrieved from the argument list -or from the resource database: -.IN "Text widget" "resources" -.ps 9 -.nr PS 9 -.vs 11 -.nr VS 11 -.TS H -lw(1.5i) lw(1i) lw(1i) lw(2i). -_ -.sp 3p -.TB -Name Type Default Description -.sp 3p -_ -.TH -.R -.sp 3p -XtNbackground Pixel XtDefaultBackground Window background color -XtNbackgroundPixmap Pixmap None Window background pixmap -XtNborderColor Pixel XtDefaultForeground Window border color -XtNborderPixmap Pixmap None Window border pixmap -XtNborderWidth Dimension 4 Border width in pixels -XtNcursor Cursor XC_xterm Pointer cursor -XtNdialogHOffset int 10 Offset of insert file dialog -XtNdialogVOffset int 10 Offset of insert file dialog -T{ -XtNdestroyCallback -T} T{ -XtCallbackList -T} T{ -NULL -T} T{ -Callbacks for -.PN XtDestroyWidget -T} -XtNdisplayCaret Boolean True Display a marker at the insert position -XtNdisplayNonPrinting Boolean True Display control char as ^C -XtNdisplayPosition int 0 Character position of first line -XtNecho Boolean True Whether or not to display output -XtNeditType XtEditType XttextRead Edit mode (see note) -T{ -XtNfile -T} T{ -char* -T} T{ -tmpnam(\|) -T} T{ -File for -.PN asciiDiskWidgetClass -T} -XtNforeground Pixel Black Foreground color -XtNfont XFontStruct* Fixed Fontname -XtNheight Dimension Font height Height of widget -XtNinsertPosition int 0 Character position of caret -XtNleftMargin Dimension 2 Left margin in pixels -T{ -XtNlength -T} T{ -int -T} T{ -String length -T} T{ -Size of the string buffer -T} -T{ -XtNmappedWhenManaged -T} T{ -Boolean -T} T{ -True -T} T{ -Whether -.PN XtMapWidget -is automatic -T} -XtNselectTypes XtTextSelectType* See below Selection units for multi-click -XtNsensitive Boolean True Whether widget receives input -T{ -XtNstring -T} T{ -char* -T} T{ -Blank -T} T{ -String for -.PN asciiStringWidgetClass -T} -XtNtextOptions int None See below -XtNtextSink XtTextSink None See below -XtNtextSource XtTextSource None See below -XtNtranslations TranslationTable See above event-to-action translations -XtNwidth Dimension 100 Width of widget (pixels) -XtNx Position 0 x coordinate in pixels -XtNy Position 0 y coordinate in pixels -.sp 3p -_ -.TE -.ps 11 -.nr PS 11 -.vs 13 -.nr VS 13 -.NT Notes -.IP 1. 5 -You cannot use -.PN XtNeditType , -.PN XtNfile , -.PN XtNlength , -and -.PN XtNfont -with the -.PN XtTextSetValues -and the -.PN XtTextGetValues -calls. -.IP 2. 5 -The -.PN XtNeditType -attribute has one of the values -.PN XttextAppend , -.PN XttextEdit , -or -.PN XttextRead . -.IP 3. 5 -If -.PN asciiStringWidgetClass -is used, the resource -.PN XtNstring -specifies a buffer containing the text to be displayed and edited. -.PN AsciiStringWidget -does not copy this buffer but uses it in-place. -.IP 4. 5 -If -.PN XtNdisplayNonPrinting -is -.PN True -any control characters will be displayed as the two-character -sequence "^", "C" where "C" is the uppercase (printing) equivalent -of the control character. If the value is -.PN False -any control characters will be displayed as a single space character. -.IP 5. 5 -If -.PN XtNecho -is -.PN False -then no text is displayed. Text may still be selected and modified, -though invisibly. -.NE -.LP -The options for the -.PN XtNtextOptions -attribute are: -.TS H -lw(1.5i) lw(4.5i). -_ -.sp 3p -.TB -Option Description -.sp 3p -_ -.TH -.R -.sp 3p -T{ -.PN editable -T} T{ -Whether or not the user is allowed to modify the text. -T} -.sp 3p -T{ -.PN resizeHeight -T} T{ -Makes a request to the parent widget to lengthen the widget -if all the text cannot fit in the window. -T} -.sp 3p -T{ -.PN resizeWidth -T} T{ -Makes a request to the parent widget to widen the widget if the -text becomes too long to fit on one line. -T} -.\".sp 3p -.\"T{ -.\".PN scrollHorizontal -.\"T} T{ -.\"Puts a scroll bar on the top of the widget. -.\"T} -.sp 3p -T{ -.PN scrollOnOverflow -T} T{ -Automatically scrolls the text up when new text is entered -below the bottom (last) line. -T} -.sp 3p -T{ -.PN scrollVertical -T} T{ -Puts a scroll bar on the left side of the widget. -T} -.sp 3p -T{ -.PN wordBreak -T} T{ -Starts a new line when a word does not fit on the current line. -T} -.sp 3p -_ -.TE -.LP -These options can be ORed together to set more than one at the same time. -.LP -.PN XtNselectionTypes -is an array of entries of type -.PN XtTextSelectType -and is used for multiclick. -As the pointer button is clicked in rapid succession, -each click highlights the next ``type'' described in the array. -.TS -lw(1.25i) lw(4.25i). -T{ -XtselectAll -T} T{ -Selects the contents of the entire buffer. -T} -.sp 6p -T{ -XtselectChar -T} T{ -Selects text characters as the pointer moves over them. -T} -.sp 6p -T{ -XtselectLine -T} T{ -Selects the entire line. -T} -.sp 6p -T{ -XtselectNull -T} T{ -Indicates the end of the selection array. -T} -.sp 6p -T{ -XtselectParagraph -T} T{ -Selects the entire paragraph (delimited by newline characters). -T} -.sp 6p -T{ -XtselectPosition -T} T{ -Selects the current pointer position. -T} -.sp 6p -T{ -XtselectWord -T} T{ -Selects whole words (delimited by whitespace) as the pointer moves onto -them. -T} -.TE -.LP -The default selectType array is: -.LP -.Ds 0 -{XtselectPosition, XtselectWord, XtselectLine, XtselectParagraph, XtselectAll, XtselectNull} -.De -.LP -For the default case, -two rapid pointer clicks highlight the current word, three clicks -highlight the current line, -four clicks highlight the current paragraph, -and five clicks highlight the entire text. -If the timeout value is exceeded, the next pointer -click returns to the first entry in the selection array. -The selection array is not copied by the Text widget. -The client must allocate space for the array -and cannot deallocate or change it until the Text widget is destroyed -or until a new selection array is set. -.NH 3 -Selection Actions -.LP -The Text widget fully supports the X selection and cut buffer mechanisms. -The following actions can be used to specify button bindings that will cause Text -to assert ownership of one or more selections, to store the selected text into a -cut buffer, and to retrieve the value of a selection or cut buffer and insert it -into the text value. -.IP \fBinsert-selection\fP(\fIname\fP[,\fIname\fP,...]) 1i -Retrieves the value of the first (left-most) named selection that exists -or the cut buffer that is not empty and inserts it into the input stream. -The specified name can be that of any selection (for example, -.PN PRIMARY -or -.PN SECONDARY ) -or a cut buffer (i.e. -.PN CUT_BUFFER0 -through -.PN CUT_BUFFER7 ). -Note that case matters. -.IP \fBselect-start\fP(\^) 1i -Unselects any previously selected text and begins selecting new text. -.sp 6p -.IP \fBselect-adjust\fP(\^) 1i -.br -.ns -.IP \fBextend-adjust\fP(\^)\ \ \ 1i -Continues selecting text from the previous start position. -.sp 6p -.IP \fBstart-extend\fP(\^) 1i -Begins extending the selection from the farthest (left or right) edge. -.sp 6p -.IP \fBselect-end\fP(\fIname\fP[,\fIname\fP,...]) 1i -.br -.ns -.IP \fBextend-end\fP(\fIname\fP[,\fIname\fP,...]) 1i -Ends the text selection, asserts ownership of the specified -selection(s) -and stores the text in the specified cut buffer(s). -The specified name can be that of a selection (for example, -.PN PRIMARY -or -.PN SECONDARY ) -or a cut buffer (i.e. -.PN CUT_BUFFER0 -through -.PN CUT_BUFFER7 ). -Note that case is significant. If -.PN CUT_BUFFER0 -is listed, the cut buffers are rotated before storing into buffer 0. -.NH 3 -Selecting Text -.LP -To enable an application to select a piece of text, use -.PN XtTextSetSelection . -.IN "XtTextSetSelection" "" "@DEF@" -.FD 0 -typedef long XtTextPosition; -.sp 6p -void XtTextSetSelection(\fIw\fP, \fIleft\fP, \fIright\fP) -.br - Widget \fIw\fP; -.br - XtTextPosition \fIleft\fP, \fIright\fP; -.FN -.IP \fIw\fP 1i -Specifies the widget ID. -.IP \fIleft\fP 1i -Specifies the character position at which the selection begins. -.IP \fIright\fP 1i -Specifies the character position at which the selection ends. -.LP -If redisplay is not disabled, -this function highlights the text and -makes it the PRIMARY selection. -.LP -.NH 3 -Unhighlighting Text -.LP -To unhighlight previously highlighted text in a widget, use -.PN XtTextUnsetSelection . -.IN "XtTextUnsetSelection" "" "@DEF@" -.FD 0 -void XtTextUnsetSelection(\fIw\fP) -.br - Widget \fIw\fP; -.FN -.LP -.NH 3 -Getting Selected Text Character Positions -.LP -To enable the application to get the character positions of the -selected text, use -.PN XtTextGetSelectionPos . -.IN "XtTextGetSelectionPos" "" "@DEF@" -.FD 0 -void XtTextGetSelectionPos(\fIw\fP, \fIpos1\fP, \fIpos2\fP) -.br - Widget \fIw\fP; -.br - XtTextPosition *\fIpos1\fP, *\fIpos2\fP; -.FN -.IP \fIw\fP 1i -Specifies the widget ID. -.IP \fIpos1\fP 1i -Specifies a pointer to the location to which the beginning character position -of the selection -is returned. -.IP \fIpos2\fP 1i -Specifies a pointer to the location to which the ending character position of -the selection is returned. -.LP -If the returned values are equal, -there is no current selection. -.NH 3 -Replacing Text -.LP -To enable an application to replace text, use -.PN XtTextReplace . -.IN "XtTextReplace" "" "@DEF@" -.FD 0 -int XtTextReplace(\fIw\fP, \fIstart_pos\fP, \fIend_pos\fP, \fItext\fP) -.br - Widget \fIw\fP; -.br - XtTextPosition \fIstart_pos\fP, \fIend_pos\fP; -.br - XtTextBlock *\fItext\fP; -.FN -.IP \fIw\fP 1i -Specifies the widget ID. -.IP \fIstart_pos\fP 1i -Specifies the starting character position of the text replacement. -.IP \fIend_pos\fP 1i -Specifies the ending character position of the text replacement. -.IP \fItext\fP 1i -Specifies the text to be inserted into the file. -.LP -The -.PN XtTextReplace -function deletes text in the specified range (startPos, endPos) -and inserts the new text at startPos. -The return value is -.PN XawEditDone -if the replacement is successful, -.PN XawPositionError -if the edit mode is -.PN XttextAppend -and startPos is -not the last character of the source, -or -.PN XawEditError -if either the source was read-only -or the range to be deleted is larger than the length of the source. -.LP -The -.PN XtTextBlock -structure (defined in -.Pn < X11/Text.h > -contains: -.LP -.IN "XtTextBlock" "" "@DEF@" -.Ds 0 -.TA .5i 1.5i 2.25i -.ta .5i 1.5i 2.25i -typedef struct { - int firstPos; - int length; - char *ptr; - Atom format; -} XtTextBlock, *TextBlockPtr; -.De -.LP -The firstPos field is the starting point to use within the ptr field. -The value is usually zero. -The length field is the number of characters that are transferred from the -ptr field. -The number of characters transferred is usually the number of characters in -ptr. -This format field indicates whether the data pointed to by \fBptr\fP is -char or wchar_t. When the associated widget has \fBinternational\fP set -to \fBfalse\fP this field must be XawFmt8Bit. When the associated -widget has \fBinternational\fP set to \fBtrue\fP this field must be -either XawFmt8Bit or XawFmtWide. -.LP -Note: Previous versions of Xaw used -.PN FMT8BIT , -which has been retained for backwards compatibility. \fBFMT8BIT\fP is -deprecated and will eventually be removed from the implementation. -The -.PN XtTextReplace -arguments \fBstart_pos\fP and \fBend_pos\fP -represent the text source character positions for the existing text that is -to be replaced by the text in -the -.PN XtTextBlock -structure. -The characters from start_pos up to but not including end_pos are deleted, -and the characters that are specified by the text block are inserted in -their place. If start_pos and end_pos are equal, no text is -deleted and the new text is inserted after start_pos. -.NT -Only ASCII text is currently supported, and -only one font can be used for each Text widget. -.NE -.NH 3 -Redisplaying Text -.LP -To redisplay a range of characters, use -.PN XtTextInvalidate . -.IN "XtTextInvalidate" "" "@DEF@" -.FD 0 -void XtTextInvalidate(\fIw\fP, \fIfrom\fP, \fIto\fP) -.br - Widget \fIw\fP; -.br - XtTextPosition \fIfrom\fP, \fIto\fP; -.FN -The -.PN XtTextInvalidate -function causes the specified range of characters to be redisplayed immediately -if redisplay is enabled or the next time that redisplay is enabled. -.LP -.sp -To enable redisplay, use -.PN XtTextEnableRedisplay . -.IN "XtTextEnableRedisplay" "" "@DEF@" -.FD 0 -void XtTextEnableRedisplay(\fIw\fP) -.br - Widget \fIw\fP; -.FN -The -.PN XtTextEnableRedisplay -function flushes any changes due to batched updates when -.PN XtTextDisableRedisplay -was called and allows future changes to be reflected immediately. -.LP -.sp -To disable redisplay while making several changes, use -.PN XtTextDisableRedisplay . -.IN "XtTextDisableRedisplay" "" "@DEF@" -.FD 0 -void XtTextDisableRedisplay(\fIw\fP) -.br - Widget \fIw\fP; -.FN -The -.PN XtTextDisableRedisplay -function causes all changes to be batched until -.PN XtTextDisplay -or -.PN XtTextEnableRedisplay -is called. -.LP -.sp -To display batched updates, use -.PN XtTextDisplay . -.IN "XtTextDisplay" "" "@DEF@" -.FD 0 -void XtTextDisplay(\fIw\fP) -.br - Widget \fIw\fP; -.FN -The -.PN XtTextDisplay -function forces any accumulated updates to be displayed. -.LP -.sp -To notify the source that the length has been changed, use -.PN XtTextSetLastPos . -.IN "XtTextSetLastPos" "" "@DEF@" -.FD 0 -void XtTextSetLastPos(\fIw\fP, \fIlast\fP); -.br - Widget \fIw\fP; -.br - XtTextPosition \fIlast\fP; -.FN -.LP -The -.PN XtTextSetLastPos -function notifies the text source that data has been added to -or removed from the end of the source. -.NH 3 -Changing Resources -.LP -The following procedures are convenience procedures that replace calls to -.PN XtSetValues -or -.PN XtGetValues -when only a single resource is to be modified or retrieved. -.LP -.sp -To assigns a new value to XtNtextOptions resource, use -.PN XtTextChangeOptions . -.IN "XtTextChangeOptions" "" "@DEF@" -.FD 0 -void XtTextChangeOptions(\fIw\fP, \fIoptions\fP) -.br - Widget \fIw\fP; -.br - int \fIoptions\fP; -.FN -.LP -.sp -To obtain the current value of XtNtextOptions for the specified widget, use -.PN XtTextGetOptions . -.IN "XtTextGetOptions" "" "@DEF@" -.FD 0 -int XtTextGetOptions(\fIw\fP) -.br - Widget \fIw\fP; -.FN -.LP -.sp -To obtain the character position of the left-most character on the -first line displayed in the widget (that is, the value of XtNdisplayPosition), use -.PN XtTextTopPosition . -.IN "XtTextTopPosition" "" @DEF@" -.FD 0 -XtTextPosition XtTextTopPosition(\fIw\fP) -.br - Widget \fIw\fP; -.FN -.LP -.sp -To move the insertion caret to the specified source position, use -.PN XtTextSetInsertionPoint . -.IN "XtTextSetInsertionPoint" "" "@DEF@" -.FD 0 -void XtTextSetInsertionPoint(\fIw\fP, \fIposition\fP) -.br - Widget \fIw\fP; -.br - XtTextPosition \fIposition\fP; -.FN -.LP -The text will be scrolled vertically if necessary to make the line containing the -insertion point visible. -The result is equivalent to setting the XtNinsertPosition resource. -.LP -.sp -To obtain the current position of the insertion caret, use -.PN XtTextGetInsertionPoint . -.IN "XtTextGetInsertionPoint" "" "@DEF@" -.FD 0 -XtTextPosition XtTextGetInsertionPoint(\fIw\fP) -.br - Widget \fIw\fP; -.FN -The result is equivalent to retrieving the value of the XtNinsertPosition resource. -.LP -.sp -To replace the text source in the specified widget, use -.PN XtTextSetSource . -.IN "XtTextSetSource" "" "@DEF@" -.FD 0 -void XtTextSetSource(\fIw\fP, \fIsource\fP, \fIposition\fP) -.br - Widget \fIw\fP; -.br - XtTextSource \fIsource\fP; -.br - XtTextPosition \fIposition\fP; -.FN -A display update will be performed if redisplay has not been disabled. -.LP -.sp -To obtain the current text source for the specified widget, use -.PN XtTextGetSource . -.IN "XtTextGetSource" "" "@DEF@" -.FD 0 -XtTextSource XtTextGetSource(\fIw\fP) -.br - Widget \fIw\fP; -.FN -.LP -.sp -To enable and disable the insert position marker, use -.PN XtTextDisplayCaret . -.IN "XtTextDisplayCaret" "" "@DEF@" -.FD 0 -void XtTextDisplayCaret(\fIw\fP, \fIvisible\fP) -.br - Widget \fIw\fP; -.br - Boolean \fIvisible\fP; -.FN -.IP \fIw\fP 1i -Specifies the widget ID of the Text widget. -.IP \fIvisible\fP 1i -Specifies whether or not the caret should be displayed. -.LP -If visible is \fBFalse\fP the insert position marker will be disabled. -The marker is re-enabled either by setting visible to \fBTrue\fP, by -calling -.PN XtSetValues , -or by executing the \fBdisplay-caret\fP action routine. -.NH 3 -Creating Sources and Sinks -.LP -The following functions for creating and destroying text sources and sinks -are called automatically by -.PN AsciiStringWidget -and -.PN AsciiDiskWidget -and it is therefore only necessary for the client to use them when creating -an instance of -.PN textWidgetClass . -.LP -.sp -To create a new ASCII text sink, use -.PN XtAsciiSinkCreate . -.IN "XtAsciiSinkCreate" "" "@DEF@" -.FD 0 -XtTextSink XtAsciiSinkCreate(\fIw\fP, \fIargs\fP, \fInum_args\fP) -.br - Widget \fIw\fP; -.br - ArgList \fIargs\fP; -.br - Cardinal \fInum_args\fP; -.FN -.LP -The resources required by the sink are -qualified by the name and class of the parent and the sub-part name -.PN XtNtextSink -and class -.PN XtCTextSink . -.LP -.sp -To deallocate an ASCII text sink, use -.PN XtAsciiSinkDestroy . -.IN "XtAsciiSinkDestroy" "" "@DEF@" -.FD 0 -void XtAsciiSinkDestroy(\fIsink\fP) -.br - XtTextSink \fIsink\fP; -.FN -.LP -The sink must not be in use by any widget or an error will result. -.LP -.sp -To create a new text disk source, use -.PN XtDiskSourceCreate . -.IN "XtDiskSourceCreate" "" "@DEF@" -.FD 0 -XtTextSource XtDiskSourceCreate(\fIw\fP, \fIargs\fP, \fInum_args\fP) -.br - Widget \fIw\fP; -.br - ArgList \fIargs\fP; -.br - Cardinal \fInum_args\fP; -.FN -.LP -The resources required by the source are -qualified by the name and class of the parent and the sub-part name -.PN XtNtextSource -and class -.PN XtCTextSource . -.LP -.sp -To deallocate a text disk source, use -.PN XtDiskSourceDestroy . -.IN "XtDiskSourceDestroy" "" "@DEF@" -.FD 0 -void XtDiskSourceDestroy(\fIsource\fP) -.br - XtTextSource \fIsource\fP; -.FN -.LP -The source must not be in use by any widget or an error will result. -.LP -.sp -To create a new text string source, use -.PN XtStringSourceCreate . -.IN "XtStringSourceCreate" "" "@DEF@" -.FD 0 -XtTextSource XtStringSourceCreate(\fIw\fP, \fIargs\fP, \fInum_args\fP) -.br - Widget \fIw\fP; -.br - ArgList \fIargs\fP; -.br - Cardinal \fInum_args\fP; -.FN -.LP -The resources required by the source are -qualified by the name and class of the parent and the sub-part name -.PN XtNtextSource -and class -.PN XtCTextSource . -.LP -.sp -To deallocate a text string source, use -.PN XtStringSourceDestroy . -.IN "XtStringSourceDestroy" "" "@DEF@" -.FD 0 -void XtStringSourceDestroy(\fIsource\fP) -.br - XtTextSource \fIsource\fP; -.FN -.LP -The source must not be in use by any widget or an error will result. -.NH 2 -Scrollbar Widget -.LP -.XS -\*(SN Scrollbar Widget -.XE -.IN "Scrollbar widget" "" "@DEF@" -The Scrollbar widget is a rectangular area that contains a slide region and -a thumb (slide bar). -A Scrollbar can be used alone, as a valuator, or it can -be used within a composite widget (for example, a Viewport). -A Scrollbar can be aligned either vertically or horizontally. -.LP -When a Scrollbar is created, -it is drawn with the thumb in a contrasting color. -The thumb is normally used to scroll client data and to give visual -feedback on the percentage of the client data that is visible. -.LP -Each pointer button invokes a specific scroll bar action. -That is, given either a vertical or horizontal alignment, -the pointer button actions will scroll or return data as appropriate -for that alignment. -Pointer buttons 1 and 3 do not perform scrolling operations by default. -Instead, they return the pixel position of the cursor on the scroll region. -When pointer button 2 is clicked, -the thumb moves to the current pointer position. -When pointer button 2 is held down and the pointer pointer is moved, -the thumb follows the pointer. -.LP -The cursor in the scroll region changes depending on the current action. -When no pointer button is pressed, -the cursor appears as an arrow that points in the direction -that scrolling can occur. -When pointer button 1 or 3 is pressed, -the cursor appears as a single-headed arrow that points in the logical -direction that the client will move the data. -When pointer button 2 is pressed, -the cursor appears as an arrow that points to the thumb. -.LP -While scrolling is in progress, -the application receives notification from callback procedures. -For both scrolling actions, -the callback returns the Scrollbar widget ID, the client_data, -and the pixel position of the pointer when the button was released. -For smooth scrolling, -the callback routine returns the scroll bar widget, the client data, -and the current relative position of the thumb. -When the thumb is moved using pointer button 2, -the callback procedure is invoked continuously. -When either button 1 or 3 is pressed, -the callback procedure is invoked only when the button is released -and the client callback procedure is responsible for moving the thumb. -.LP -The class variable for the Scrollbar widget is -.PN scrollbarWidgetClass . -.LP -When creating a Scrollbar widget instance, -the following resources are retrieved from the argument list -or from the resource database: -.IN "Scrollbar widget" "resources" -.ps 9 -.nr PS 9 -.vs 11 -.nr VS 11 -.TS H -lw(1.5i) lw(1i) lw(1i) lw(2i). -_ -.sp 3p -.TB -Name Type Default Description -.sp 3p -_ -.TH -.R -.sp 3p -XtNbackground Pixel white Window background color -XtNbackgroundPixmap Pixmap None Window background pixmap -XtNborderColor Pixel XtDefaultForeground Window border color -XtNborderPixmap Pixmap None Window border pixmap -XtNborderWidth Dimension 1 Width of button border -T{ -XtNdestroyCallback -T} T{ -XtCallbackList -T} T{ -NULL -T} T{ -Callbacks for -.PN XtDestroyWidget -T} -XtNforeground Pixel black Thumb color -XtNheight Dimension See below Height of scroll bar -XtNjumpProc XtCallbackList NULL Callback for thumb select -XtNlength Dimension None Major dimension (height of XtorientVertical) -T{ -XtNmappedWhenManaged -T} T{ -Boolean -T} T{ -True -T} T{ -Whether -.PN XtMapWidget -is automatic -T} -T{ -XtNorientation -T} T{ -XtOrientation -T} T{ -XtorientVertical -T} T{ -Orientation (vertical or horizontal) -T} -T{ -XtNscrollDCursor -T} T{ -Cursor -T} T{ -XC_sb_down_arrow -T} T{ -Cursor for scrolling down -T} -T{ -XtNscrollHCursor -T} T{ -Cursor -T} T{ -XC_sb_h_double_arrow -T} T{ -Idle horizontal cursor -T} -T{ -XtNscrollLCursor -T} T{ -Cursor -T} T{ -XC_sb_left_arrow -T} T{ -Cursor for scrolling left -T} -XtNscrollProc XtCallbackList NULL Callback for the slide region -T{ -XtNscrollRCursor -T} T{ -Cursor -T} T{ -XC_sb_right_arrow -T} T{ -Cursor for scrolling right -T} -T{ -XtNscrollUCursor -T} T{ -Cursor -T} T{ -XC_sb_up_arrow -T} T{ -Cursor for scrolling up -T} -T{ -XtNscrollVCursor -T} T{ -Cursor -T} T{ -XC_sb_v_double_arrow -T} T{ -Idle vertical cursor -T} -XtNsensitive Boolean True Whether widget receives input -XtNshown float NULL Percentage the thumb covers -XtNthickness Dimension 14 Minor dimension (height if XtorientHorizontal) -XtNthumb Pixmap Grey Thump pixmap -XtNtop float NULL Position on scroll bar -XtNtranslations TranslationTable See below Event-to-action translations -XtNwidth Dimension See below Width of scroll bar -XtNx Position NULL x position of scroll bar -XtNy Position NULL y position of scroll bar -.sp 3p -_ -.TE -.ps 11 -.nr PS 11 -.vs 13 -.nr VS 13 -.LP -The class for all cursor resources is -.PN XtCCursor . -.LP -You can set the dimensions of the Scrollbar two ways. -As for all widgets, -you can use the -.PN XtNwidth -and -.PN XtNheight -resources. -In addition, -you can use an alternative method that is independent of the vertical -or horizontal orientation: -.TS -lw(1.5i) lw(4.5i). -T{ -.PN XtNlength -T} T{ -Specifies the height for a vertical Scrollbar -and the width for a horizontal Scrollbar. -T} -T{ -.PN XtNthickness -T} T{ -Specifies the width for a vertical Scrollbar -and the height for a horizontal Scrollbar. -T} -.TE -.LP -.IN "Scrollbar widget" "creating" -.IN "Creating widgets" "Scrollbar" -To create a Scrollbar widget instance, use -.PN XtCreateWidget -and specify the class variable -.PN scrollbarWidgetClass . -.LP -.IN "Scrollbar widget" "destroying" -.IN "Destroying widgets" "Scrollbar" -To destroy a Scrollbar widget instance, use -.PN XtDestroyWidget -and specify the widget ID for the Scrollbar. -.LP -.sp -The arguments to the -.PN XtNscrollProc -callback procedure are: -.IN "ScrollProc" "" "@DEF@" -.FD 0 -void \fIScrollProc\fP(\fIscrollbar\fP, \fIclient_data\fP, \fIposition\fP) -.br - Widget \fIscrollbar\fP; -.br - caddr_t \fIclient_data\fP; -.br - caddr_t \fIposition\fP; /* int */ -.FN -.IP \fIscrollbar\fP 1i -Specifies the ID of the Scrollbar. -.IP \fIclient_data\fP 1i -Specifies the client data. -.IP \fIposition\fP 1i -Returns the pixel position of the thumb in integer form. -.LP -The -.PN XtNscrollProc -callback is used for incremental scrolling -and is called by the \fBNotifyScroll\fP action. -The position argument is a signed quantity and should be cast to an int -when used. -Using the default button bindings, -button 1 returns a positive value, -and button 3 returns a negative value. -In both cases, -the magnitude of the value is the distance of the pointer in pixels from the -top (or left) of the Scrollbar. -The value will never be less than zero or greater than the length -of the Scrollbar. -.LP -.sp -The arguments to the -.PN XtNjumpProc -callback procedure are: -.IN "JumpProc" "" "@DEF@" -.FD 0 -void \fIJumpProc\fP(\fIscrollbar\fP, \fIclient_data\fP, \fIpercent\fP) -.br - Widget \fIscrollbar\fP; -.br - caddr_t \fIclient_data\fP; -.br - caddr_t \fIpercent_ptr\fP; /* float* */ -.FN -.IP \fIscrollbar\fP 1i -Specifies the ID of the scroll bar widget. -.IP \fIclient_data\fP 1i -Specifies the client data. -.IP \fIpercent_ptr\fP 1i -Specifies the floating point position of the thumb (0.0 \- 1.0). -.LP -The -.PN XtNjumpProc -callback is used to implement smooth scrolling and is called by the -\fBNotifyThumb\fP -action. Percent_ptr must be cast to a pointer to float before -use; i.e. -.LP -.Ds 0 -.TA .5i -.ta .5i - float percent = *(float*)percent_ptr; -.De -.LP -With the default button bindings, -button 2 moves the thumb interactively, -and the -.PN XtNjumpProc -is called on each new position of the pointer. -.NT -An older interface used -.PN XtNthumbProc -and passed the percentage by value rather than by reference. -This interface is not portable across machine architectures -and therefore is no longer supported but is still implemented -for those (non-portable) applications which used it. -.NE -.LP -.IN "Scrollbar widget" "setting thumb values" -To set the position and length of a Scrollbar thumb, use -.PN XtScrollbarSetThumb . -.IN "XtScrollbarSetThumb" "" "@DEF@" -.FD 0 -void XtScrollbarSetThumb(\fIw\fP, \fItop\fP, \fIshown\fP) -.br - Widget \fIw\fP; -.br - float \fItop\fP; -.br - float \fIshown\fP; -.FN -.IP \fIw\fP 1i -Specifies the Scrollbar widget ID. -.IP \fItop\fP 1i -Specifies the position of the top of the thumb as a fraction of the -length of the Scrollbar. -.IP \fIshown\fP 1i -Specifies the length of the thumb as a fraction of the total length -of the Scrollbar. -.LP -.PN XtScrollbarThumb -moves the visible thumb to position (0.0 \- 1.0) and length (0.0 \- 1.0). -Either the top or shown arguments can be specified as \-1.0, -in which case the current value is left unchanged. -Values greater than 1.0 are truncated to 1.0. -.LP -If called from -.PN XtNjumpProc , -.PN XtScrollbarSetThumb -has no effect. -.LP -.sp -The actions supported by the Scrollbar widget are: -.IP \fBStartScroll\fP(\fIvalue\fP) 1i -The possible values are Forward, Backward, or Continuous. -This must be the first action to begin a new movement. -.IP \fBNotifyScroll\fP(\fIvalue\fP) 1i -The possible values are Proportional or FullLength. -If the argument to StartScroll was Forward or Backward, -NotifyScroll executes the -.PN XtNscrollProc -callbacks -and passes either the position of the pointer if its argument is Proportional -or the full length of the scroll bar if its argument is FullLength. -If the argument to StartScroll was Continuous, -NotifyScroll returns without executing any callbacks. -.IP \fBEndScroll\fP(\^) 1i -This must be the last action after a movement is complete. -.IP \fBMoveThumb\fP(\^) 1i -Repositions the scroll bar thumb to the current pointer location. -.IP \fBNotifyThumb\fP(\^)\ \ \ 1i -Calls the -.PN XtNjumpProc -callbacks and passes the relative position of the -pointer as a percentage of the scroll bar length. -.LP -The default bindings for Scrollbar are: -.LP -.Ds 0 -.TA .5i 1.75i -.ta .5i 1.75i - <Btn1Down>: StartScroll(Forward) - <Btn2Down>: StartScroll(Continuous) MoveThumb(\|) NotifyThumb(\|) - <Btn3Down>: StartScroll(Backward) - <Btn2Motion>: MoveThumb(\|) NotifyThumb(\|) - <BtnUp>: NotifyScroll(Proportional) EndScroll(\|) -.De -.LP -Examples of additional bindings a user might wish to specify in a -resource file are: -.LP -.Ds 0 -.TA .5i 2.25i -.ta .5i 2.25i -*Scrollbar.Translations: \\ - ~Meta<KeyPress>space: StartScroll(Forward) NotifyScroll(FullLength) \\n\\ - Meta<KeyPress>space: StartScroll(Backward) NotifyScroll(FullLength) \\n\\ - EndScroll(\|) -.De -.NH 2 -Viewport Widget -.LP -.XS -\*(SN Viewport Widget -.XE -.IN "Viewport widget" "" "@DEF@" -The Viewport widget consists of a frame window, one or two Scrollbars, -and an inner window. -The frame window is determined by -the viewing size of the data that is to be displayed -and the dimensions to which the Viewport is created. -The inner window is the full size of the data that is to be displayed -and is clipped by the frame window. -The Viewport widget controls the scrolling of the data directly. -No application callbacks are required for scrolling. -.LP -When the geometry of the frame window is equal in size to the inner window, -or when the data does not require scrolling, -the Viewport widget automatically removes any scroll bars. -The -.PN forceBars -option causes the Viewport widget to display any scroll bar permanently. -.LP -The class variable for the Viewport widget is -.PN viewportWidgetClass . -.LP -When creating a Viewport widget instance, -the following resources are retrieved from the argument list -or from the resource database: -.IN "Viewport widget" "resources" -.ps 9 -.nr PS 9 -.vs 11 -.nr VS 11 -.TS H -lw(1.5i) lw(1i) lw(1i) lw(2i). -_ -.sp 3p -.TB -Name Type Default Description -.sp 3p -_ -.TH -.R -.sp 3p -XtNallowHoriz Boolean False Flag to allow horizontal scroll bars -XtNallowVert Boolean False Flag to allow vertical scroll bars -XtNbackground Pixel XtDefaultBackground Window background color -XtNbackgroundPixmap Pixmap None Window background pixmap -XtNborderColor Pixel XtDefaultForeground Window border color -XtNborderPixmap Pixmap None Window border pixmap -XtNborderWidth Dimension 1 Width of the border in pixels -T{ -XtNdestroyCallback -T} T{ -XtCallbackList -T} T{ -NULL -T} T{ -Callback for -.PN XtDestroyWidget -T} -XtNforceBars Boolean False Flag to force display of scroll bars -XtNheight Dimension height of child Height of the widget -T{ -XtNmappedWhenManaged -T} T{ -Boolean -T} T{ -True -T} T{ -Whether -.PN XtMapWidget -is automatic -T} -XtNsensitive Boolean True Whether widget should receive input -XtNtranslations TranslationTable None Event-to-action translations -XtNuseBottom Boolean False Flag to indicate bottom/top bars -XtNuseRight Boolean False Flag to indicate right/left bars -XtNwidth Dimension width of child Width of the widget -XtNx Position 0 x coordinate within parent -XtNy Position 0 y coordinate within parent -.sp 3p -_ -.TE -.ps 11 -.nr PS 11 -.vs 13 -.nr VS 13 -.LP -The Viewport widget manages a single child widget. -When the size of the child is larger than the size of the Viewport, -the user can interactively move the child within the Viewport -by repositioning the Scrollbars. -.LP -The default size of the Viewport before it is realized is the -width and/or height of the child. -After it is realized, the viewport will allow its -child to grow vertically or horizontally if -.PN XtNallowVert -or -.PN XtNallowHoriz -were set, respectively. If the corresponding vertical or horizontal -scrolling were not enabled, the viewport will propagate the -geometry request to its own parent and the child will be allowed -to change size only if the (grand) parent allows it. Regardless -of whether or not scrolling was enabled in the corresponding -direction, if the child requests a new size smaller than the -viewport size, the change will be allowed only if the parent of -the viewport allows the viewport to shrink to the appropriate dimension. -.LP -.IN "Viewport widget" "creating" -To create a Viewport widget instance, use -.PN XtCreateWidget -and specify the class variable -.PN viewportWidgetClass . -.LP -.IN "Viewport widget" "inserting a child" -To insert a child into a Viewport widget, use -.PN XtCreateWidget -and specify the widget ID of the previously created Viewport as the parent. -.LP -.IN "Viewport widget" "removing a child" -To remove a child from a Viewport widget, use -.PN XtUnmanageChild -or -.PN XtDestroyWidget -and specify the widget ID of the child. -.LP -.IN "Viewport widget" "destroying" -.IN "Destroying widgets" "Viewport" -To delete the inner window, any children, and the frame window, use -.PN XtDestroyWidget -and specify the widget ID of the Viewport widget. -.NH 2 -Box Widget -.LP -.XS -\*(SN Box Widget -.XE -.IN "Box widget" "" "@DEF@" -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 when children are added or deleted. -The Box widget always attempts to pack its children as closely as possible -within the geometry allowed by its parent. -.LP -Box widgets are commonly used to manage a related set of Command -widgets and are frequently called ButtonBox widgets, but the children are -not limited to buttons. -.LP -The children are arranged on a background that -has its own specified dimensions and color. -.LP -The class variable for the Box widget is -.PN boxWidgetClass . -.LP -When creating a Box widget instance, -the following resources are retrieved from the argument list -or from the resource database: -.IN "Box widget" "resources" -.ps 9 -.nr PS 9 -.vs 11 -.nr VS 11 -.TS H -lw(1.5i) lw(1i) lw(1i) lw(2i) . -_ -.sp 3p -.TB -Name Type Default Description -.sp 3p -_ -.TH -.R -.sp 3p -XtNbackground Pixel XtDefaultBackground Window background color -XtNbackgroundPixmap Pixmap None Window background pixmap -XtNborderColor Pixel XtDefaultForeground Window border color -XtNborderPixmap Pixmap None Window border pixmap -XtNborderWidth Dimension 1 Border width on button box -T{ -XtNdestroyCallback -T} T{ -XtCallbackList -T} T{ -NULL -T} T{ -Callbacks for -.PN XtDestroyWidget -T} -XtNhSpace Dimension 4 Pixel distance left and right of children -XtNheight Dimension see below Viewing height of inner window -T{ -XtNmappedWhenManaged -T} T{ -Boolean -T} T{ -True -T} T{ -Whether -.PN XtMapWidget -is automatic -T} -XtNtranslations TranslationTable None Event-to-action translations -XtNvSpace Dimension 4 Pixel distance top and bottom of children -XtNwidth Dimension width of widest child Viewing width of inner window -XtNx Position 0 Widget location x coordinate -XtNy Position 0 Widget location y coordinate -.sp 3p -_ -.TE -.ps 11 -.nr PS 11 -.vs 13 -.nr VS 13 -.LP -The Box widget positions its children in rows with -.PN XtNhSpace -pixels to the left and right of each child and -.PN XtNvSpace -pixels between rows. -If the Box width is not specified, -the Box widget uses the width of the widest child. -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. -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 it parent and will begin the -layout process from the beginning if a new width is granted. -After positioning all children, -the Box widget attempts to shrink its own size to the minimum dimensions -required for the layout. -.LP -.IN "Box widget" "creating" -.IN "Creating widgets" "Box" -To create a box widget instance, use -.PN XtCreateWidget -and specify the class variable -.PN boxWidgetClass . -.LP -.IN "Box widget" "adding children" -To add a child to the Box, use -.PN XtCreateWidget -and specify the widget ID of the Box as the parent of the new widget. -.LP -.IN "Box widget" "removing children" -To remove a child from the Box, use -.PN XtUnmanageChild -or -.PN XtDestroyWidget -and specify the widget ID of the child. -.LP -.IN "Box widget" "destroying" -.IN "Destroying widgets" "Box" -To destroy a Box widget instance, use -.PN XtDestroyWidget -and specify the widget ID of the Box widget. -All the children of this box are automatically destroyed at the same time. -.\".NH 2 -.\"MenuBox Widget -.\".LP -.\".XS -.\"\*(SN MenuBox Widget -.\".XE -.\".IN "MenuBox widget" "" "@DEF@" -.\"The MenuBox widget allows for menus of arbitrary complexity. -.\"A MenuBox consists of a main window and a number of entries that -.\"are added to it. -.\"Although these entries typically are Command widgets, -.\"any kind of widget can be added to a MenuBox. -.\".LP -.\"The class variable for the MenuBox widget is -.\".PN menuBoxWidgetClass . -.\".LP -.\"An application can use the MenuBox widget to create: -.\".IP \(bu 5 -.\"Pop-up menus -.\".IP \(bu 5 -.\"Pull-down menus -.\".IP \(bu 5 -.\"Cascading menus -.\".LP -.\"For example, to create a pop-up menu, -.\"use -.\".PN XtCreateWidget -.\"and specifies the class variable -.\".PN menuBoxWidgetClass . -.\"This creates an empty main window. -.\"Then, to create a menu item that is to be added to the MenuBox, -.\"specify the widget ID of this empty menu as the parent -.\"of each new item. -.\".LP -.\"The MenuBox can arrange its children either vertically or horizontally. -.\".LP -.\"The MenuBox widget automatically makes all items the same width -.\"(for vertical orientation) or the same height (for horizontal orientation) -.\"as the largest one passed to it. -.\"Then, to make the MenuBox visible, -.\"use -.\".PN XtRealize -.\"to map the MenuBox widget. -.\".LP -.\"When creating a MenuBox widget, -.\"the following resources are retrieved from the argument list -.\"or from the resource database: -.\".IN "MenuBox widget" "resources" -.\".ps 9 -.\".nr PS 9 -.\".vs 11 -.\".nr VS 11 -.\".TS H -.\"lw(1.5i) lw(1i) lw(1i) lw(2i). -.\"_ -.\".sp 3p -.\".TB -.\"Name Type Default Description -.\".sp 3p -.\"_ -.\".TH -.\".R -.\".sp 3p -.\"XtNbackgroundPixmap Pixmap None Window background pixmap -.\"XtNborderPixmap Pixmap None Window border pixmap -.\"XtNwidth Dimension 1 Menu window width -.\"XtNheight Dimension 1 Menu window height -.\"XtNorientation XtOrientation XtorientVertical Row/column layout -.\"XtNborderWidth Dimension 1 Menu window border width -.\"XtNborder Pixmap BlackPixmap Border color -.\"XtNbackground int WhitePixel Background color -.\"T{ -.\"XtNinternalWidth -.\"T} T{ -.\"int -.\"T} T{ -.\"2 -.\"T} T{ -.\"Space between first item and top -.\".br -.\"Space between last item and bottom -.\"T} -.\"XtNinternalHeight int 2 First menu item to window top -.\"XtNspace int 1 Space between menu items -.\"XtNtranslations TranslationTable None event-to-action translations -.\"XtNx Position 0 Widget location x coordinate -.\"XtNy Position 0 Widget location y coordinate -.\"XtNcallback XtCallbackList Dummy Callback function -.\".sp 3p -.\"_ -.\".TE -.\".ps 11 -.\".nr PS 11 -.\".vs 13 -.\".nr VS 13 -.\".LP -.\".IN "MenuBox widget" 'creating" -.\".IN "Creating widgets" "MenuBox" -.\"To create a MenuBox widget instance, use -.\".PN XtCreateWidget -.\"and specify the class variable -.\".PN menuBoxWidgetClass . -.\".LP -.\".IN "MenuBox widget" "adding entries" -.\"To add entries, -.\"specify the widget ID of the previously created MenuBox widget -.\"as the parent of each new entry. -.\".LP -.\".IN "MenuBox widget" "deleting entries" -.\"To delete an entry, use -.\".PN XtUnmanageChild -.\"or -.\".PN XtDestroyWidget -.\"and specify the widget ID of the entry. -.\".LP -.\"The MenuBox widget resides in whatever parent widget the application specifies. -.\"For example, it does not automatically create a pop-up widget. -.\"To create a pop-up menu, use -.\".PN XtCreatePopupShell -.\"and then create the MenuBox as a child of this newly created shell. -.\".LP -.\".IN "MenuBox widget" "over-riding geometry manager" -.\"The MenuBox widget has a built-in geometry manager that enables the menu to -.\"become as large as necessary. -.\"To override the built-in geometry manager, -.\"create your own geometry manager and call it -.\".PN XtMenuGeometryManager . -.\".IN "XtMenuGeometryManager" "" "@DEF@" -.\".FD 0 -.\"GeometryReturnCode XtMenuGeometryManager(\fIw\fP, \fIrequest\fP, \ -.\"\fIrequest_box\fP, \fIreply_box\fP) -.\".br -.\" Widget \fIw\fP; -.\".br -.\" int \fIrequest\fP; -.\".br -.\"XtWidgetGeometry *\fIrequest_box\fP, *\fIreply_box\fP; -.\".FN -.\".IP \fIw\fP 1i -.\"Specifies the widget ID. -.\".IP \fIrequest\fP 1i -.\"Specifies the geometry management request. -.\".IP \fIrequest_box\fP 1i -.\"Specifies the desired widget geometry. -.\".IP \fIreply_box\fP 1i -.\"Specifies an argument to which the allowed widget size is returned. -.\".LP -.\".IN "MenuBox widget" "destroying" -.\".IN "Destroying widgets" "MenuBox" -.\"To destroy a MenuBox widget instance, -.\"use -.\".PN XtDestroyWidget -.\"and specify the widget ID of the MenuBox widget. -.NH 2 -VPaned Widget -.LP -.XS -\*(SN VPaned Widget -.XE -.IN "VPaned widget" "" "@DEF@" -The VPaned widget manages children in a vertically tiled fashion. -A region, called a grip, appears on the border between each child. -When the pointer is positioned on a grip and pressed, -an arrow is displayed that indicates the significant pane that is -being resized. -While keeping the pointer button down, -the user can move the pointer up or down. -This, in turn, changes the window borders, causing one pane to shrink -and some other pane to grow. -The cursor indicates the pane that is of interest to the user; -some other pane in the opposite direction will be chosen to grow -or shrink an equal amount. The choice of alternate pane is a -function of the -.PN XtNmin , -.PN XtNmax -and -.PN XtNskipAdjust -constraints on the other panes. With the default bindings, -button 1 resizes the pane above the selected grip, button 3 -resizes the pane below the selected grip and button 2 repositions -the border between two panes only. -.LP -The class variable for the VPaned widget is -.PN vPanedWidgetClass . -.LP -When creating a VPaned widget instance, -the following resources are retrieved from the argument list -or from the resource database: -.IN "VPaned widget" "resources" -.ps 9 -.nr PS 9 -.vs 11 -.nr VS 11 -.TS H -lw(1.5i) lw(1i) lw(1i) lw(2i) . -_ -.sp 3p -.TB -Name Type Default Description -.sp 3p -_ -.TH -.R -.sp 3p -XtNbackground Pixel XtDefaultBackground Window background color -XtNbackgroundPixmap Pixmap None Window background pixmap -T{ -XtNbetweenCursor -T} T{ -Cursor -T} T{ -XC_sb_left_arrow -T} T{ -Cursor for changing the boundary between two panes -T} -XtNborderColor Pixel XtDefaultForeground Window border color -XtNborderPixmap Pixmap None Window border pixmap -XtNborderWidth Dimension 1 Border width (pixels) -T{ -XtNdestroyCallback -T} T{ -XtCallbackList -T} T{ -NULL -T} T{ -Callbacks for -.PN XtDestroyWidget -T} -XtNforeground Pixel Black Pixel value for the foreground color -XtNgripCursor Cursor XC_sb_v_double_arrow Cursor for grip when not active -XtNgripIndent Position 10 Offset of grip from margin (pixels) -XtNgripTranslations TranslationTable internal button bindings for grip -XtNheight Dimension sum of child heights Height of vPane -T{ -XtNlowerCursor -T} T{ -Cursor -T} T{ -XC_sb_down_arrow -T} T{ -Cursor for resizing pane below grip -T} -T{ -XtNmappedWhenManaged -T} T{ -Boolean -T} T{ -True -T} T{ -Whether -.PN XtMapWidget -is automatic -T} -XtNrefigureMode Boolean On Whether vPane should adjust children -XtNsensitive Boolean True Whether widget receives input -XtNtranslations TranslationTable None Event-to-action translations -T{ -XtNupperCursor -T} T{ -Cursor -T} T{ -XC_sb_up_arrow -T} T{ -Cursor for resizing pane above grip -T} -XtNwidth Dimension width of widest child Width of vPane -XtNx Position 0 x position of vPane -XtNy Position 0 y position of vPane -.sp 3p -_ -.TE -.ps 11 -.nr PS 11 -.vs 13 -.nr VS 13 -.LP -.IN "VPaned widget" "creating" -.IN "Creating widgets" "VPaned" -To create a VPaned widget instance, use -.PN XtCreateWidget -and specify the class variable -.PN vPanedWidgetClass . -.LP -Once the parent frame is created, -you then add panes to it. -Any type of widget can be paned. -.LP -.IN "VPaned widget" "adding pane" -To add a child pane to a VPaned frame, use -.PN XtCreateWidget -and specify the widget ID of the VPaned widget -as the parent of each new child pane. -.LP -During the creation of a child pane, -the following resources, -by which the VPaned widget controls the placement of the child, -can be specified in the argument list or retrieved from the resource database: -.IN "VPaned widget" "child resources" -.LP -.ps 9 -.nr PS 9 -.vs 11 -.nr VS 11 -.TS H -lw(1.5i) lw(1i) lw(1i) lw(2i) . -_ -.sp 3p -.TB -Name Type Default Description -.sp 3p -_ -.TH -.R -.sp 3p -T{ -XtNallowResize -T} T{ -Boolean -T} T{ -False -T} T{ -If False, ignore child resize requests -T} -XtNmax Dimension unlimited Maximum height for pane -XtNmin Dimension 1 Minimum height for pane -T{ -XtNskipAdjust -T} T{ -Boolean -T} T{ -False -T} T{ -True if VPaned widget should not automatically resize pane -T} -.sp 3p -_ -.TE -.ps 11 -.nr PS 11 -.vs 13 -.nr VS 13 -.LP -.IN "VPaned widget" "deleting pane" -To delete a pane from a vertically paned window frame, use -.PN XtUnmanageWidget -or -.PN XtDestroyWidget -and specify the widget ID of the child pane. -.LP -.IN "VPaned widget" "enable pane resizing" -.IN "VPaned widget" "disable pane resizing" -To enable or disable a child's request for pane resizing, -use -.PN XtPanedAllowResize . -.IN "XtPanedAllowResize" "" "@DEF@" -.FD 0 -void XtPanedAllowResize(\fIw\fP, \fIallow_resize\fP) -.br - Widget \fIw\fP; -.br - Boolean \fIallow_resize\fP; -.FN -.IP \fIw\fP 1i -Specifies the widget ID of the child widget pane. -.IP \fIallow_resize\fP -Enables or disables a pane widget for resizing requests. -.LP -If allow_resize is -.PN True , -VPane allows geometry requests from the child to change the pane's height. -If allow_resize is -.PN False , -VPane ignores geometry requests from the child to change the pane's height. -The default state is -.PN True -before the VPane is realized and -.PN False -after it is realized. -This procedure is equivalent to changing the -.PN XtNallowResize -resource for the child. -.LP -.sp -.IN "VPaned widget" "change height settings" -To change the minimum and maximum height settings for a pane, use -.PN XtPanedSetMinMax . -.IN "XtPanedSetMinMax" "" "@DEF@" -.FD 0 -void XtPanedSetMinMax(\fIw\fP, \fImin\fP, \fImax\fP) -.br - Widget \fIw\fP; -.br - int \fImin\fP, \fImax\fP; -.FN -.IP \fIw\fP 1i -Specifies the widget ID of the child widget pane. -.IP \fImin\fP 1i -New minimum height of the child, expressed in pixels. -.IP \fImax\fP 1i -New maximum height of the child, expressed in pixels. -.LP -This procedure is equivalent to setting the -.PN XtNmin -and -.PN XtNmax -resources for the child. -.LP -.sp -.IN "VPaned widget" "enable auto-reconfiguring" -.IN "VPaned widget" "disable auto-reconfiguring" -To enable or disable automatic recalculation of pane sizes and positions, -use -.PN XtPanedSetRefigureMode . -.IN "XtPanedSetRefigureMode" "" "@DEF@" -.FD 0 -void XtPanedSetRefigureMode(\fIw\fP, \fImode\fP) -.br - Widget \fIw\fP; -.br - Boolean \fImode\fP; -.FN -.IP \fIw\fP 1i -Specifies the widget ID of the VPaned widget. -.IP \fImode\fP 1i -Enables or disables refiguration. -.LP -You should set the mode to FALSE if you add multiple panes to -or remove multiple panes from the parent frame after it has been realized, -unless you can arrange to manage all the panes at once using -.PN XtManageChildren . -After all the panes are added, set the mode to TRUE. -This avoids unnecessary geometry calculations and ``window dancing''. -.LP -.IN "VPaned widget" "destroying" -.IN "Destroying widgets" "VPaned" -To delete an entire VPaned widget and all associated data structures, -use -.PN XtDestroyWidget -and specify the widget ID of the VPaned widget. -All the children of the VPaned widget -are automatically destroyed at the same time. -.NH 2 -Form Widget -.LP -.XS -\*(SN Form Widget -.XE -.IN "Form widget" "" "@DEF@" -The Form widget can contain an arbitrary number of children or subwidgets. -The Form provides geometry management for its children, -which allows individual control of the position of each child. -Any combination of children can be added to a Form. -The initial positions of the children may be computed relative to -the positions of other children. -When the Form is resized, -it computes new positions and sizes for its children. -This computation is based upon information provided -when a child is added to the Form. -.LP -The class variable for a Form widget is -.PN formWidgetClass . -.LP -When creating a Form widget instance, -the following resources are retrieved from the argument list -or from the resource database: -.IN "Form widget" "resources" -.ps 9 -.nr PS 9 -.vs 11 -.nr VS 11 -.TS H -lw(1.5i) lw(1i) lw(1i) lw(2i). -_ -.sp 3p -.TB -Name Type Default Description -.sp 3p -_ -.TH -.R -.sp 3p -XtNbackground Pixel XtDefaultBackground Window background color -XtNbackgroundPixmap Pixmap None Window background pixmap -XtNborderColor Pixel XtDefaultForeground Window border color -XtNborderPixmap Pixmap None Window border pixmap -XtNborderWidth Dimension 1 Width of border in pixels -T{ -XtNdefaultDistance -T} T{ -int -T} T{ -4 -T} T{ -Default value for XtNhorizDistance -.br -and XtNvertDistance -T} -T{ -XtNdestroyCallback -T} T{ -XtCallbackList -T} T{ -NULL -T} T{ -Callbacks for -.PN XtDestroyWidget -T} -XtNheight Dimension computed at realize Height of form -T{ -XtNmappedWhenManaged -T} T{ -Boolean -T} T{ -True -T} T{ -Whether -.PN XtMapWidget -is automatic -T} -XtNsensitive Boolean True Whether widget receives input -XtNtranslations TranslationTable None Event-to-action translations -XtNwidth Dimension computed at realize Width of form -XtNx Position NULL x position of form -XtNy Position NULL y position of form -.sp 3p -_ -.TE -.ps 11 -.nr PS 11 -.vs 13 -.nr VS 13 -.LP -.IN "Form widget" "creating" -.IN "Creating widgets" "Form" -To create a Form widget instance, use -.PN XtCreateWidget -and specify the class variable -.PN formWidgetClass . -.LP -.IN "Form widget" "adding children" -To add a new child to a Form, use -.PN XtCreateWidget -and specify the widget ID of the previously created Form as the parent -of the child. -.LP -When creating children that are to be added to a Form, -the following additional resources are retrieved from the -argument list or from the resource database: -.IN "Form widget" "child resources" -.ps 9 -.nr PS 9 -.vs 11 -.nr VS 11 -.TS H -lw(1.5i) lw(1i) lw(1i) lw(2i). -_ -.sp 3p -.TB -Name Type Default Description -.sp 3p -_ -.TH -.R -.sp 3p -XtNbottom XtEdgeType XtRubber See text -XtNfromHoriz Widget NULL See text -XtNfromVert Widget NULL See text -XtNhorizDistance int XtdefaultDistance See text -XtNleft XtEdgeType XtRubber See text -XtNresizable Boolean FALSE TRUE if allowed to resize -XtNright XtEdgeType XtRubber See text -XtNtop XtEdgeType XtRubber See text -XtNvertDistance int XtdefaultDistance See text -.sp 3p -_ -.TE -.ps 11 -.nr PS 11 -.vs 13 -.nr VS 13 -.LP -When a widget is added to a Form, constraints -can be specified to the Form to indicate -where the child should be positioned within the Form. -.LP -The resources -.PN XtNhorizDistance -and -.PN XtNfromHoriz -let the -widget position itself a specified number of pixels horizontally -away from another -widget in the form. -As an example, -.PN XtNhorizDistance -could equal 10 and -.PN XtNfromHoriz -could be the widget ID of -another widget in the Form. -The new widget will be placed -10 pixels to the right of the -widget defined in -.PN XtNfromHoriz . -If -.PN XtNfromHoriz -equals NULL, then -.PN XtNhorizDistance -is measured from the left edge of the Form. -.LP -Similarly, the resources -.PN XtNvertDistance -and -.PN XtNfromVert -let -the widget position itself a specified number of pixels vertically -away from another widget in the Form. -If -.PN XtNfromVert -equals -NULL, then -.PN XtNvertDistance -is measured from the top of the Form. -Form provides a StringToWidget conversion procedure. Using this -procedure, the resource database may be used to specify the -.PN XtNfromHoriz -and -.PN XtNfromVert -resources by widget name rather than widget id. The string value -must be the name of a child of the same Form widget parent. -.LP -The -.PN XtNtop , -.PN XtNbottom , -.PN XtNleft , -and -.PN XtNright -resources tell the Form where to position the child when the Form is -resized. -.PN XtEdgeType -is defined in -.Pn < X11/Form.h > -and is one of -.IN "XtEdgeType" "" "@DEF@" -.PN XtChainTop , -.PN XtChainBottom , -.PN XtChainLeft , -.PN XtChainRight -or -.PN XtRubber . -.LP -The values -.PN XtChainTop , -.PN XtChainBottom , -.PN XtChainLeft , -and -.PN XtChainRight -specify that a constant distance from an edge of the child to -the top, bottom, left, and right edges respectively of the Form is to be -maintained. -The value -.PN XtRubber -specifies that a proportional distance from the edge of the child to -the left or top edge of the Form is to be maintained when the -form is resized. The proportion is determined from the initial -position of the child and the initial size of the Form. -Form provides a StringToEdgeType conversion procedure to allow the resize -constraints to be easily specified in a resource file. -.LP -The default width of the Form is the minimum width needed to -enclose the children after computing their initial layout, with a -margin of -.PN XtNdefaultDistance -at the right and bottom edges. If a width and height is assigned -to the Form that is too small for the layout, the children will -be clipped by the right and bottom edges of the Form. -.LP -.IN "Form widget" "deleting children" -To remove a child from a Form, use -.PN XtUnmanageChild -or -.PN XtDestroyWidget -and specify the widget ID of the child widget. -.LP -.IN "Form widget" "destroying" -.IN "Destroying widgets" "Form" -To destroy a Form widget instance, use -.PN XtDestroyWidget -and specify the widget ID of the Form. -All children of the Form are automatically destroyed at the same -time. -.LP -When a new child becomes managed or an old child unmanaged, Form -will recalculate the positions of its children according to the -values of the -.PN XtNhorizDistance , -.PN XtNfromHoriz , -.PN XtNvertDistance -and -.PN XtNfromVert -constraints at the time the change is made. -No re-layout is performed when a child makes a -geometry request. -.LP -.sp -To force or defer a re-layout of the Form, use -.PN XtFormDoLayout . -.IN "Form widget" "re-layout" -.IN "XtFormDoLayout" "" "@DEF@" -.FD 0 -void XtFormDoLayout(\fIw\fP, \fIdo_layout\fP) -.br - Widget \fIw\fP; -.br - Boolean \fIdo_layout\fP; -.FN -.IP \fIw\fP 1i -Specifies the Form widget. -.IP \fIdo_layout\fP 1i -Enables (if -.PN True ) -or disables (if -.PN False ) -layout of the Form widget. -.LP -When making several changes to the children of a Form widget -after the Form has been realized, it is a good idea to disable -re-layout until all changes have been made, then allow the -layout. Form increments an internal count each time -.PN XtFormDoLayout -is called with do_layout -.PN False -and decrements the count when do_layout is -.PN True . -When the count reaches 0, Form performs a re-layout. -.NH 2 -Dialog Widget -.LP -.XS -\*(SN Dialog Widget -.XE -.IN "Dialog widget" "" "@DEF@" -The Dialog widget implements a commonly used interaction -semantic to prompt for auxiliary input from a user. -For example, you can use a Dialog widget when an application -requires a small piece of information, such as a file name, from the user. -A Dialog widget is simply a special case of the Form widget -that provides a convenient way to create a ``preconfigured form''. -.LP -The typical Dialog widget contains three areas. -The first line contains a -description of the function of the Dialog widget, -for example, the string ``Filename:''. -The second line contains an area into which the user types input. -The third line can contain buttons that let the user confirm -or cancel the Dialog input. -.LP -The class variable for the Dialog widget is -.PN dialogWidgetClass . -.LP -When creating a Dialog widget instance, -the following resources are retrieved from the argument list -or from the resource database: -.IN "Dialog widget" "resources" -.ps 9 -.nr PS 9 -.vs 11 -.nr VS 11 -.TS H -lw(1.5i) lw(1i) lw(1i) lw(2i). -_ -.sp 3p -.TB -Name Type Default Description -.sp 3p -_ -.TH -.R -XtNbackground Pixel XtDefaultBackground Window background color -XtNbackgroundPixmap Pixmap None Window background pixmap -XtNborderColor Pixel XtDefaultForeground Window border color -XtNborderPixmap Pixmap None Window border pixmap -XtNborderWidth Dimension 1 Width of border in pixels -T{ -XtNdestroyCallback -T} T{ -XtCallbackList -T} T{ -NULL -T} T{ -Callbacks for -.PN XtDestroyWidget -T} -XtNheight Dimension computed at create Height of dialog -XtNlabel String Label name String to be displayed -T{ -XtNmappedWhenManaged -T} T{ -Boolean -T} T{ -True -T} T{ -Whether -.PN XtMapWidget -is automatic -T} -XtNmaximumLength int 256 Length of input buffer -XtNsensitive Boolean True Whether widget receives input -XtNtranslations TranslationTable None Event-to-action translations -XtNvalue char* NULL Pointer to default value string -XtNwidth Dimension computed at create Width of dialog -XtNx Position NULL x position of dialog -XtNy Position NULL y position of dialog -.sp 3p -_ -.TE -.ps 11 -.nr PS 11 -.vs 13 -.nr VS 13 -.LP -The instance name of the label widget within the Dialog widget is ``label'', -and the instance name of the Dialog value widget is ``value''. -.LP -.IN "Dialog widget" "creating" -.IN "Creating widgets" "Dialog" -To create a Dialog widget instance, you can use -.PN XtCreateWidget -and specify the class variable -.PN dialogWidgetClass . -.LP -.IN "Dialog widget" "adding children" -To add a child button to the Dialog box, use -.PN XtCreateWidget -and specify widget ID of the previously created Dialog box as the parent -of each child. -When creating buttons, -you do not have to specify form constraints. -The Dialog box will automatically add the constraints. -.LP -.sp -To return the character string in the text field, use -.PN XtDialogGetValueString . -.IN "XtDialogGetValueString" "" "@DEF@" -.FD 0 -char *XtDialogGetValueString(\fIw\fP) -.br - Widget \fIw\fP; -.FN -.IP \fIw\fP 1i -Specifies the widget ID of the Dialog box. -.LP -If a string was specified in the -.PN XtNvalue -resource, Dialog copy the string internally and will use it as the -initial (i.e. default) value for the input text. The value string -may be freed immediately after creating the Dialog widget. If the -length of the value string is greater than the maximumLength resource, -the larger value is used. -.LP -If no value resource is specified for the Dialog widget, the text user -input area is not displayed. In order to display a blank input area, -an empty string must be passed as the value resource. -.LP -.sp -.IN "Dialog widget" "removing children" -To remove a child button from the Dialog box, use -.PN XtUnmanageChild -or -.PN XtDestroyWidget -and specify the widget ID of the child. -.LP -.IN "Dialog widget" "destroying" -.IN "Destroying widgets" "Dialog" -To destroy a Dialog widget instance, use -.PN XtDestroyWidget -and specify the widget ID of the Dialog widget. -All children of the Dialog are automatically destroyed at the same time. -.NH 2 -List Widget -.LP -.XS -\*(SN List Widget -.XE -.IN "List widget" "" "@DEF@" -The List widget is a rectangle that contains a list of strings formatted -into rows and columns. -When one of the strings is selected, -it is highlighted, and an application callback routine is invoked. -.\"When the cursor pointer is clicked on one of the strings -.\"it is shown to be selected by highlighting and the application's -.\"callback routine is invoked. -.LP -The class variable for the List widget is -.PN listWidgetClass . -.LP -When creating a List widget instance, -the following resources are retrieved from the argument list -or from the resource database: -.IN "List widget" "resources" -.ps 9 -.nr PS 9 -.vs 11 -.nr VS 11 -.TS H -lw(1.5i) lw(1i) lw(1i) lw(2i). -_ -.sp 3p -.TB -Name Type Default Description -.sp 3p -_ -.TH -.R -.sp 3p -XtNbackground Pixel XtDefaultBackground Window background color -XtNbackgroundPixmap Pixmap None Window background pixmap -XtNborderColor Pixel XtDefaultForeground Window border color -XtNborderPixmap Pixmap None Window border pixmap -XtNborderWidth Dimension 1 Width of border -XtNcallback XtCallbackList NULL Selection callback function -XtNcolumnSpacing Dimension 6 Space between columns in the list -XtNcursor Cursor left_ptr Pointer cursor -XtNdefaultColumns int 2 Number of columns to use -T{ -XtNdestroyCallback -T} T{ -XtCallbackList -T} T{ -NULL -T} T{ -Callbacks for -.PN XtDestroyWidget -T} -XtNfont XFontStruct* XtDefaultFont Font for list text -XtNforceColumns Boolean False Force the use of XtNdefaultColumns -XtNforeground Pixel XtDefaultForeground Foreground (text) color -XtNheight Dimension Contains list exactly Height of widget -XtNinsensitiveBorder Pixmap Gray Border when not sensitive -T{ -XtNinternalHeight -T} T{ -Dimension -T} T{ -2 -T} T{ -Spacing between list and widget edges -T} -T{ -XtNinternalWidth -T} T{ -Dimension -T} T{ -4 -T} T{ -Spacing between list and widget edges -T} -XtNlist String * List name An array of strings that is the list -T{ -XtNlongest -T} T{ -int -T} T{ -Longest item -T} T{ -Length of the longest list item in pixels -T} -T{ -XtNmappedWhenManaged -T} T{ -Boolean -T} T{ -True -T} T{ -Whether -.PN XtMapWidget -is automatic -T} -T{ -XtNnumberStrings -T} T{ -int -T} T{ -Number of strings -T} T{ -Number of items in the list -T} -XtNpasteBuffer Boolean False Copy the selected item to cut buffer 0 -XtNrowSpacing Dimension 4 Space between rows in the list -XtNsensitive Boolean True Whether widget receives input -XtNtranslations TranslationTable None Event-to-action translations -XtNverticalList Boolean False Specify the layout of list items -XtNwidth Dimension Contains list exactly Width of widget -XtNx Position 0 Widget x coordinate -XtNy Position 0 Widget y coordinate -.sp 3p -_ -.TE -.ps 11 -.nr PS 11 -.vs 13 -.nr VS 13 -.LP -The new resources associated with the List widget are: -.TS -lw(1.7i) lw(4i). -T{ -.PN XtNcolumnSpacing -.br -.PN XtNrowSpacing -T} T{ -Specify the amount of space between each of the rows and columns in the list. -T} -.sp -T{ -.PN XtNdefaultColumns -T} T{ -Specifies the default number of columns, -which is used when neither the width nor the height of the List widget -is specified or when XtNforceColumns is -.PN True . -T} -.sp 6p -T{ -.PN XtNforceColumns -T} T{ -Specifies that the default number of columns is to be used -no matter what the current size of the List widget is. -T} -.sp 6p -T{ -.PN XtNheight -T} T{ -Specifies the height of the List widget. -The default value is the minimum height that will contain -the entire list with the spacing values specified. -If the specified height is larger than the minimum, -the list is put in the upper left corner. -T} -.sp 6p -T{ -.PN XtNinternalHeight -T} T{ -Represents a margin, in pixels, between the top and bottom -of the list and the edges of the List widget. -T} -.sp 6p -T{ -.PN XtNinternalWidth -T} T{ -Represents a margin, in pixels, between the left and right edges -of the list and the edges of the List widget. -T} -.sp 6p -T{ -.PN XtNlist -T} T{ -Specifies the array of text strings that is to displayed in the List widget. -If the default for XtNnumberStrings is used, -the list must be null-terminated. -If a value is not specified for the list, -the number of strings is set to 1, -and the name of the widget is used as the list. -T} -.sp 6p -T{ -.PN XtNlongest -T} T{ -Specifies the length of the longest string in the current list in pixels. -If the client knows the length, -it should specify it. -The List widget will compute a default length by searching through the list. -T} -.sp 6p -T{ -.PN XtNnumberStrings -T} T{ -Specifies the number of strings in the current list. -If a value is not specified, -the list must be null-terminated. -T} -.sp 6p -T{ -.PN XtNpasteBuffer -T} T{ -If this is -.PN True , -then the value of the string selected will be put -into X cut buffer 0. -T} -.sp 6p -T{ -.PN XtNsensitive -T} T{ -If set to -.PN False , -the List widget will change its window border to -.PN XtNinsensitiveBorder -and display all items in the list as stippled strings. -While the List widget is insensitive, -no item in the list can be selected or highlighted. -T} -.sp 6p -T{ -.PN XtNverticalList -T} T{ -If this is -.PN True , -the elements in the list are arranged vertically; if -.PN False , -the elements are arranged horizontally. -T} -.sp 6p -T{ -.PN XtNwidth -T} T{ -Specifies the width of the List widget. -The default value is the minimum width that will contain -the entire list with the spacing values specified. -If the specified width is larger than the minimum, -the list is put in the upper left corner. -T} -.TE -.LP -The List widget has three predefined actions: Set, Unset, and Notify. -Set and Unset allow switching the foreground and background colors -for the current list item. -Notify allows processing application callbacks. -.LP -The following is the default translation table used by the List Widget: -.LP -.Ds -.TA .5i 2.25i -.ta .5i 2.25i -<Btn1Down>,<Btn1Up>: Set(\|) Notify(\|) -.De -.LP -.IN "List widget" "creating" -.IN "Creating widgets" "List" -To create a List widget instance, use -.PN XtCreateWidget -and specify the class variable -.PN listWidgetClass . -.LP -.IN "List widget" "destroying" -.IN "Destroying widgets" "list" -To destroy a List widget instance, use -.PN XtDestroyWidget -and specify the widget ID of the List widget. -.LP -The List widget supports two callback lists: -.IP \(bu 5 -.PN XtNdestroyCallback -.IP \(bu 5 -.PN XtNcallback -.LP -The notify action executes the callbacks on the the -.PN XtNcallback -list. -.LP -The call_data argument passed to callbacks on the -.PN XtNcallback -list is a pointer to an -.PN XtListReturnStruct -structure, defined in -.Pn < X11/List.h >: -.LP -.Ds 0 -.TA .5i 2.25i -.ta .5i 2.25i -.IN "XtListReturnStruct" "" "@DEF@" -typedef struct _XtListReturnStruct { - String string; /* string shown in the list. */ - int index; /* index of the item selected. */ -} XtListReturnStruct; -.De -.NH 3 -Changing the List -.LP -To change the list that is displayed, use -.PN XtListChange . -.IN "XtListChange" "" "@DEF@" -.FD 0 -void XtListChange(\fIw\fP, \fIlist\fP, \fInitems\fP, \fIlongest\fP, \fIresize\fP) -.br - Widget \fIw\fP; -.br - String * \fIlist\fP; -.br - int \fInitems\fP, \fIlongest\fP; -.br - Boolean \fIresize\fP; -.FN -.IP \fIw\fP 1i -Specifies the widget ID. -.IP \fIlist\fP 1i -Specifies the new list for the list widget to display. -.IP \fInitems\fP 1i -Specifies the number of items in the list. -If a value less than 1 is specified, -list must be null terminated. -.IP \fIlongest\fP 1i -Specifies the length of the longest item in the list in pixels. -If a value less than 1 is specified, -the List widget calculates the value for you. -.IP \fIresize\fP 1i -Specifies a Boolean value that indicates whether the List widget should try -to resize itself -.Pn ( True ) -or not -.Pn ( False ) -after making the change. -Note that the constraints of the parent of this widget are always enforced, -regardless of the value specified. -.LP -.PN XtListChange -changes the list of strings that the List widget is to display. -.NH 3 -Highlighting an Item -.LP -To highlight an item in the list use, -.PN XtListHighlight -.IN "XtListHighlight" "" "@DEF@" -.FD 0 -void XtListHighlight(\fIw\fP, \fIitem\fP); -.br - Widget \fIw\fP; -.br - int \fIitem\fP; -.FN -.IP \fIw\fP 1i -Specifies the widget ID. -.IP \fIitem\fP 1i -Specifies the index into the current list that indicates the item -to be highlighted. -.LP -Only one item can be highlighted at a time. -If an item is already highlighted when -.PN XtListHighlight -is called, -the highlighted item is immediately unhighlighted and -the new item is highlighted. -.NH 3 -Unhighlighting an Item -.LP -To unhighlight the currently highlighted item in the list, use -.PN XtListUnhighlight -.IN "XtListUnhighlight" "" "@DEF@" -.FD 0 -void XtListUnhightlight(\fIw\fP); -.br - Widget \fIw\fP; -.FN -.IP \fIw\fP 1i -Specifies the widget ID. -.NH 3 -Retrieving the Currently Selected Item -.LP -To retrieve an item in the list use, -.PN XtListShowCurrent -.IN "XtListShowCurrent" "" "@DEF@" -.FD 0 -XtListReturnStruct *XtListShowCurrent(\fIw\fP); -.br - Widget \fIw\fP; -.FN -.IP \fIw\fP 1i -Specifies the widget ID. -.LP -The -.PN XtListShowCurrent -function returns a pointer to an -.PN XtListReturnStruct -structure, -contains the currently highlighted item. -If the value of the index member is XT_LIST_NONE, -.IN "XT_LIST_NONE" -the string member is undefined, -which indicates that no item is currently selected. -.\"------------------------------------------------------------------------ -.NH 2 -Grip Widget -.LP -.XS -\*(SN Grip Widget -.XE -.IN "Grip widget" "" "@DEF@" -.LP -The Grip widget provides a small region in which user input -events -(such as -.PN ButtonPress or -.PN ButtonRelease ) -may be handled. -The most common use for the grip is as an attachment -point for visually repositioning an object, -such as the pane border in a VPaned widget. -.LP -The class variable for the Grip widget is -.PN gripWidgetClass . -.LP -When creating a Grip widget instance, -the following resources are retrieved from the argument list -or from the resource database: -.ps 9 -.nr PS 9 -.vs 11 -.nr VS 11 -.TS H -lw(1.5i) lw(1i) lw(1i) lw(2i). -_ -.sp 3p -.TB -Name Type Default Description -.sp 3p -_ -.TH -.R -.sp 3p -XtNborderColor Pixel XtDefaultForeground Window border color -XtNborderPixmap Pixmap None Window border pixmap -XtNborderWidth Dimension 0 Width of the border in pixels -XtNcallback XtCallbackList None Action routine -XtNcursor Cursor None Cursor for the grip -T{ -XtNdestroyCallback -T} T{ -XtCallbackList -T} T{ -NULL -T} T{ -Callback for -.PN XtDestroyWidget -T} -XtNforeground Pixel XtDefaultForeground Window background color -XtNheight Dimension 8 Height of the widget -T{ -XtNmappedWhenManaged -T} T{ -Boolean -T} T{ -True -T} T{ -Whether -.PN XtMapWidget -is automatic -T} -XtNsensitive Boolean True Whether widget should receive input -XtNtranslations TranslationTable None Event-to-action translations -XtNwidth Dimension 8 Width of the widget -XtNx Position 0 x coordinate within parent -XtNy Position 0 y coordinate within parent -.sp 3p -_ -.TE -.ps 11 -.nr PS 11 -.vs 13 -.nr VS 13 -.LP -Note that the Grip widget displays its region with the foreground pixel only. -.LP -The Grip widget does not declare any default event translation bindings, -but it does declare a single action routine named GripAction -in its action table. -The client specifies an arbitrary -event translation table giving parameters to the GripAction routine. -.LP -The -.PN GripAction -action executes the callbacks on the -.PN XtNcallback -list, passing as call_data a pointer to a -.PN GripCallData -structure, defined in -.Pn < X11/Grip.h > : -.LP -.Ds 0 -.TA .5i 2.25i -.ta .5i 2.25i -.IN "GripCallData" "" "@DEF@" -.IN "GripCallDataRec" "" "@DEF@" -typedef struct _GripCallData { - XEvent *event; - String *params; - Cardinal num_params; -} GripCallDataRec, *GripCallData; -.De -.LP -In this structure, the event field is a pointer to the input -event that triggered the action, and params and num_params give -the string parameters specified in the translation table for the -particular event binding. -.IN "Grip widget" "GripAction table" -.LP -The following is an example of a GripAction translation table: -.LP -.Ds 0 -.TA .5i 2.5i -.ta .5i 2.5i - <Btn1Down>: GripAction(press) - <Btn1Motion>: GripAction(move) - <Btn1Up>: GripAction(release) -.De -For a complete description of the format of action routines, -see the \fI\*(xT\fP. -.LP -.IN "Grip widget" "creating" -.IN "Creating widgets" "Grip" -To create a Grip widget instance, use -.PN XtCreateWidget -and specify the class variable -.PN gripWidgetClass . -.LP -.IN "Grip widget" "destroying" -.IN "Destroying widgets" "Grip" -To destroy a Command button widget instance, use -.PN XtDestroyWidget -and specify the ID of the Grip widget. -.\"------------------------------------------------------------------------ -.NH 2 -Toggle Widget -.LP -.XS -\*(SN Toggle Widget -.XE -.IN "Toggle widget" "" "@DEF@" - -The Toggle widget is a rectanglular button that contains a text label -or pixmap. This widget maintains a Boolean state (e.g. True/False or -On/Off) and changes state whenever it is selected. When the pointer -cursor is on the Toggle it highlights to indicate that the Toggle is -available for selection. When the pointer button is pressed the -Toggle is selected. This causes the state of the Toggle to reverse -and its callback routine to be invoked. -.LP -Toggle buttons may also be part of a radio group. A radio group is a -list of Toggle buttons in which only one Toggle may be set at any -time. A radio group is identified by giving the widget id of any one -of its members. There is a convenience routine, -.PN XtToggleGetCurrent -that will return information about the Toggle in the radio group that is -currently set. More information on radio groups is presented below. -.LP -The class variable for the Toggle widget is -.PN toggleWidgetClass . -.LP -When creating a Toggle widget instance, -the following resources are retrieved from the argument list -or from the resource database: -.IN "Toggle widget" "resources" -.ps 9 -.nr PS 9 -.vs 11 -.nr VS 11 -.TS H -lw(1.5i) lw(1i) lw(1i) lw(2i). -_ -.sp 3p -.TB -Name Type Default Description -.sp 3p -_ -.TH -.R -.sp 3p -XtNbackground Pixel XtDefaultBackground Window background color -XtNbackgroundPixmap Pixmap None Window background pixmap -T{ -XtNbitmap -T} T{ -Pixmap -T} T{ -None -T} T{ -Pixmap to display in place of the label -T} -XtNborderColor Pixel XtDefaultForeground Window border color -XtNborderPixmap Pixmap None Window border pixmap -XtNborderWidth Dimension 1 Width of button border -XtNcallback XtCallbackList NULL Callback for button select -XtNcursor Cursor None Pointer cursor -T{ -XtNdestroyCallback -T} T{ -XtCallbackList -T} T{ -NULL -T} T{ -Callbacks for -.PN XtDestroyWidget -T} -XtNfont XFontStruct* XtDefaultFont Label font -XtNforeground Pixel XtDefaultForeground Foreground color -XtNheight Dimension Text height Button height -T{ -XtNhighlightThickness -T} T{ -Dimension -T} T{ -2 -T} T{ -Width of border to be highlighted -T} -XtNinsensitiveBorder Pixmap Gray Border when not sensitive -T{ -XtNinternalHeight -T} T{ -Dimension -T} T{ -2 -T} T{ -Internal border height for highlighting -T} -T{ -XtNinternalWidth -T} T{ -Dimension -T} T{ -4 -T} T{ -Internal border width for highlighting -T} -XtNjustify XtJustify XtJustifyCenter Type of text alignment -XtNlabel String Button name Button label -T{ -XtNmappedWhenManaged -T} T{ -Boolean -T} T{ -True -T} T{ -Whether -.PN XtMapWidget -is automatic -T} -XtNradioData Pointer Name of widget Value that will be returned by \fBXtToggleGetCurrent\fP -XtNradioGroup Widget NULL Any other widget in the Toggle's radio group -XtNresize Boolean True Whether to auto-resize in \fBSetValues\fP -XtNsensitive Boolean True Whether widget receives input -XtNstate Boolean Off State of the Toggle widget -XtNtranslations TranslationTable see below Event-to-action translations -XtNwidth Dimension Text width Button width -XtNx Position 0 x coordinate -XtNy Position 0 y coordinate -.sp 3p -_ -.TE -.ps 11 -.nr PS 11 -.vs 13 -.nr VS 13 -.TS -lw(1.7i) lw(4i). -T{ -.PN XtNbitmap -T} T{ -Specifies a bitmap to display in place of the text label -[See the description of this resource in the Label widget for -further details]. -T} -.sp 6p -T{ -.PN XtNcallback -T} T{ -Specifies the callback list of functions to be called when the -Toggle widget changes state. This usually occurs when the Toggle -widget's notify action is called, but when a toggle is in a radio -group it may change state at other times. The places where -this can occur include: -.PN XtToggleSetCurrent , -.PN XtToggleUnsetCurrent , -.PN XtToggleChangeRadioGroup , -the -.PN set -action, -.PN XtSetValues, -and -.PN XtCreateWidget. -T} -.sp 6p -T{ -.PN XtNheight -T} T{ -Specifies the height of the Toggle widget. -The default value is the minimum height that will contain: -.br -\fBXtNinternalheight\fP + height of \fBXtNlabel\fP + \fBXtNinternalHeight\fP -.br -If the specified height is larger than the minimum, -the label string is centered vertically. -T} -.sp 6p -T{ -.PN XtNinternalHeight -T} T{ -Represents the distance in pixels between the top and bottom -of the label text or bitmap and the horizontal edges of the Toggle widget. -HighlightThickness can be larger or smaller than this value. -T} -.sp 6p -T{ -.PN XtNinternalWidth -T} T{ -Represents the distance in pixels between the ends of the label text -or bitmap and the vertical edges of the Toggle widget. -HighlightThickness can be larger or smaller than this value. -T} -.sp 6p -T{ -.PN XtNjustify -T} T{ -Specifies left, center, or right alignment of the label string -within the Toggle widget. -If it is specified within an -.PN ArgList , -one of the values -.PN XtJustifyLeft , -.PN XtJustifyCenter , -or -.PN XtJustifyRight -can be specified. -In a resource of type ``string'', -one of the values ``left'', ``center'', or ``right'' can be specified. -T} -.sp 6p -T{ -.PN XtNlabel -T} T{ -Specifies the text string that is to be displayed in the Toggle widget -if no bitmap is specified. -The default is the widget name of the Toggle widget. -T} -.sp 6p -T{ -.PN XtNradioData -T} T{ -Specifies the data that will be returned from a call to -.PN XtToggleGetCurrent -if this widget is the one that is set in a radio group. This data is -also used to identify the toggle that will be set by a call to -.PN XtToggleSetCurrent. -The value NULL is returned by -.PN XtToggleGetCurrent -if no widget is set in a radio group. Programmers not -specify NULL as \fBXtNradioData\fP, if they intend to use -\fBXtToggleGetCurrent\fP -T} -.sp 6p -T{ -.PN XtNradioGroup -T} T{ -Specifies another Toggle widget which is in the radio group to which this -Toggle widget should be added. A radio group is a group of Toggle widgets, -only one of which may be "set" at a time. If this value is NULL (the default) -then the Toggle will not be part of any radio group and can -change state without effecting any other Toggle widgets. If the -widget specified in this resource is not already in a radio group -then a new radio group will be created containing these two -Toggle widgets. No Toggle widget can be in multiple radio groups. -T} -.sp 6p -T{ -.PN XtNresize -T} T{ -Specifies whether the Toggle widget should attempt to resize to its -preferred dimensions whenever -.PN XtSetValues -is called for it. -The default is -.PN True . -T} -.sp 6p -T{ -.PN XtNsensitive -T} T{ -If set to -.PN False , -the Toggle widget will change its window border to -.PN XtNinsensitiveBorder -and will stipple the label string. -T} -.sp 6p -T{ -.PN XtNstate -T} T{ -Specifies whether the Toggle widget is set (True/On) or unset (False/Off). -T} -.sp 6p -T{ -.PN XtNwidth -T} T{ -Specifies the width of the Toggle widget. -The default value is the minimum width that will contain: -.br -\fBXtNinternalwidth\fP + width of \fBXtNlabel\fP + \fBXtNinternalWidth\fP -.br -If the width is larger or smaller than the minimum, -.PN XtNjustify -determines how the label string is aligned. -T} -.TE -.LP -The Toggle widget supports the following actions: -.IP \(bu 5 -Switching the button between the foreground and background -colors with \fBset\fP, \fBunset\fP and \fBtoggle\fP -.IP \(bu 5 -Processing application callbacks with \fBnotify\fP. -.IP \(bu 5 -Switching the internal border between highlighted -and unhighlighted states with \fBhighlight\fP and \fBunhighlight\fP -.LE -.LP -The following are the default translation bindings that are used -by the Toggle widget: -.LP -.Ds 0 -.TA .5i 2.25i -.ta .5i 2.25i - <EnterWindow>: highlight(Always) - <LeaveWindow>: unhighlight(\|) - <Btn1Down>,<Btn1Up>: toggle(\|) notify(\|) -.De -.LP -With these bindings, the user can cancel the action before -releasing the button by moving the pointer out of the Toggle widget. -.NH 3 -Toggle Actions -.LP -The full list of actions supported by the Toggle widget is: -.IP \fBhighlight\fP(\fIvalue\fP) 1.5i -Displays the internal highlight border in the color (\fBXtNforeground\fP -or -.PN XtNbackground ) -that contrasts with the interior color of the Toggle widget. -This action procedure takes one of the following conditions: WhenUnset and -Always. If no argument is passed then WhenUnset is assumed, this maintains -backwards compatibility. -.IP \fBunhighlight\fP(\|) 1.5i -Displays the internal highlight border in the color (\fBXtNforeground\fP -or -.PN XtNbackground ) -that matches the interior color of the Toggle widget. -.IP \fBset\fP(\|) 1.5i -Enters the "set" state, in which \fBnotify\fP is possible and displays the -interior of the button in the -.PN XtNforeground -color. The label is displayed -in the -.PN XtNbackground -color. If the widget to be set is in a radio -group then this procedure may unset another widget, which will -cause all routines on its callback list to be invoked. Since only one -toggle in a radio group may be set at a time the callback routines for -the toggle that is to be unset will be called before the one that -is to be set. -.IP \fBunset\fP(\|) 1.5i -Cancels the "set" state and displays the interior of the button in the -.PN XtNbackground -color. The label is displayed in the -.PN XtNforeground -color. -.IP \fBtoggle\fP(\|) 1.5i -Changes the current state of the Toggle widget, causing to be set -if it was previously unset, and unset if it was previously set. -If the widget is to be set, and is in a radio group then this procedure may -unset another widget, which will cause all routines on its callback list -to be invoked. Since only one toggle in a radio -group may be set at a time the callback routines for the toggle that -is to be unset will be called before the one that is to be set. -.IP \fBreset\fP(\|) 1.5i -Cancels any \fBset\fP or \fBhighlight\fP and displays the interior of the -button in the -.PN XtNbackground -color, with the label displayed in the -.PN XtNforeground -color. -.IP \fBnotify\fP(\|) 1.5i -Executes the -.PN XtNcallback -callback list. The call_data contains a Boolean which is -the current state of the widget. -.LP -.IN "Toggle widget" "creating" -.IN "Creating widgets" "Toggle" -To create a Toggle widget instance, use -.PN XtCreateWidget -and specify the class variable -.PN toggleWidgetClass . -.LP -.IN "Toggle widget" "destroying" -.IN "Destroying widgets" "toggle" -To destroy a Toggle widget instance, use -.PN XtDestroyWidget -and specify the widget ID of the Toggle widget. -.LP -The Toggle widget supports two callbacks: -.PN XtNdestroyCallback -and -.PN XtNcallback . -The notify action executes the callbacks on the the -.PN XtNcallback -list. -.SH -Changing the Toggle's Radio Group. -.LP -To enable an application to change the Toggle's current radio group, add -the Toggle to a radio group, or remove the Toggle from a radio group, use -.PN XtToggleChangeRadioGroup. -.IN ""XtToggleChangeRadioGroup"" "@DEF@" -.sp 6p -void XtToggleChangeRadioGroup(\fIw\fP, \fIradio_group\fP) -.br - Widget \fIw\fP, \fIradio_group\fP; -.FN -.IP \fIw\fP 1i -Specifies the widget ID of the Toggle widget. -.IP \fIradio_group\fP 1i -This should be any Toggle on the new radio group. If NULL then the Toggle -will be removed from any radio group of which it is a member. -.LP -If a toggle is already in the set state in the new radio group, -and the toggle to be added is also set then the previously set toggle in -the new radio group is unset and its callback procedures are -invoked. -.SH -Finding the Currently selected Toggle in a radio group of Toggles -.LP -To find the currently selected Toggle in a radio group of Toggle widgets -use -.PN XtToggleGetCurrent. -.IN ""XtToggleGetCurrent"" "@DEF@" -.sp 6p -caddr_t XtToggleGetCurrent(\fIradio_group\fP); -.br - Widget \fIradio_group\fP; -.FN -.IP \fIradio_group\fP 1i -Specifies the widget ID of any Toggle in the radio group. -.LP -The value returned by this function is the data pointed to by -.PN XtNradioData, -for the Toggle in the radio group that is currently set. The default -value for -.PN XtNradioData -is the name of that Toggle widget. If no Toggle -is set in the radio group specified then NULL is returned. -.SH -Changing the Toggle that is set in a radio group. -.LP -To change the Toggle that is currently set in a radio group use -.PN XtToggleSetCurrent. -.IN ""XtToggleSetCurrent"" "@DEF@" -.sp 6p -void XtToggleSetCurrent(\fIradio_group\fP, \fIradio_data\fP); -.br - Widget \fIradio_group\fP; - caddr_t \fIradio_data\fP; -.FN -.IP \fIradio_group\fP 1i -Specifies the widget ID of any Toggle in the radio group. -.IP \fIradio_data\fP 1i -Specifies the -.PN XtNradioData -identifying the Toggle that should be set in the radio group specified -by the \fIradio_group\fP argument. -.LP - -\fBXtToggleSetCurrent\fP locates the Toggle widget to be set by -matching \fIradio_data\fP against the \fBXtNradioData\fP for each -Toggle in the radio group. If none match \fBXtToggleSetCurrent\fP -returns without making any changes. If more than one Toggle matches, -\fBXtToggleSetCurrent\fP will choose a Toggle to set arbitrarily. If -this causes any Toggle widgets to change state all routines in their -callback lists will be invoked. Since only one toggle in a radio -group may be set at a time the callback routines for a Toggle that -is to be unset will be called before the one that is to be set. - -.SH -Unsetting all Toggles in a radio group. -.LP -To unset all Toggle widgets in a radio group use -.PN XtToggleUnsetCurrent. -.IN ""XtToggleUnsetCurrent"" "@DEF@" -.sp 6p -void XtToggleUnsetCurrent(\fIradio_group\fP); -.br - Widget \fIradio_group\fP; -.FN -.IP \fIradio_group\fP 1i -Specifies the widget ID of any Toggle in the radio group. -.LP -If this causes a Toggle widget to change state all routines on its -callback list will be invoked. -.\"------------------------------------------------------------------------ -.NH 2 -Template Widget - Creating A Custom Widget -.LP -.XS -\*(SN Template Widget - Creating A Custom Widget -.XE -.IN "Template widget" "" "@DEF@" -.LP -Although the task of creating a new widget may at first appear a little -daunting, there is a basic simple pattern that all widgets follow. The -Athena widget library contains three files that are intended to assist -in writing a custom widget. -.LP -Reasons for wishing to write a custom widget include: -.IP \(bu 3 -Convenient access to resource management procedures to obtain fonts, -colors, etc., even if user customization is not desired. -.IP \(bu 3 -Convenient access to user input dispatch and translation management procedures. -.IP \(bu 3 -Access to callback mechanism for building higher-level application libraries. -.IP \(bu 3 -Customizing the interface or behavior of an existing widget to suit a -special application need. -.IP \(bu 3 -Desire to allow user customization of resources such as fonts, colors, -etc., or to allow convenient re-binding of keys and buttons to internal -functions. -.IP \(bu 3 -Converting a non-Toolkit application to use the Toolkit. -.LP -In each of these cases, the operation needed to create a new widget is -to "subclass" an existing one. If the desired semantics of the new -widget are similar to an existing one, then the implementation of the -existing widget should be examined to see how much work would be -required to create a subclass that will then be -able to share the existing class methods. Much time will be saved in -writing the new widget if an existing widget class Expose, Resize and/or -GeometryManager method can be shared by the subclass. -.LP -Note that some trivial uses of a ``bare-bones'' widget may be achieved by -simply creating an instance of the Core -widget. The class variable to use when creating a Core widget is -.PN widgetClass . -The geometry of the Core widget is determined entirely by the parent widget. -.LP -It is very often the case than an application will have a special need -for a certain set of functions and that many copies of these functions -will be needed. For example, when converting an older application to use -the Toolkit, it may be desireable to have a "Window Widget" class that -might have the following semantics: -.IP \(bu 3 -Allocate 2 drawing colors in addition to a background color. -.IP \(bu 3 -Allocate a text font. -.IP \(bu 3 -Execute an application-supplied function to handle exposure events. -.IP \(bu 3 -Execute an application-supplied function to handle user input events. -.LP -It is obvious that a completely general-purpose WindowWidgetClass could -be constructed that would export all class methods as callbacks lists, -but such a widget would be very large and would have to choose some -arbitrary number of resources such as colors to allocate. An application -that used many instances of the general-purpose widget would therefore -un-necessarily waste many resources. -.LP -.sp -In this section, an outline will be given of the procedure to follow to -construct a special-purpose widget to address the items listed above. -The reader should refer to the appropriate sections of the \fI\*(xT\fP -for complete details of the material outlined here. Section 1.4 of -the \fI\*(xI\fP should be read in conjunction with this section. -.LP -All Athena widgets have three separate files associated with them: -.LP -.IP \(bu 3 -A "public" header file containing declarations needed by -applications programmers -.IP \(bu 3 -A "private" header file containing additional declarations needed by the -widget and any subclasses -.IP \(bu 3 -A source code file containing the implementation of the widget -.LP -This separation of functions into three files is suggested for all -widgets, but nothing in the Toolkit actually requires this format. In -particular, a private widget created for a single application may easily -combine the "public" and "private" header files into a single file, or -merge the contents into another application header file. Similarly, the -widget implementation can be merged into other application code. -.LP -.sp -In the following example, the public header file -.Pn < X11/Template.h >, -the private header file -.Pn < X11/TemplateP.h > -and the source code file -.Pn < X11/Template.c > -will be modified to produce the "WindowWidget" described above. -In each case, the files have been designed so that a global string -replacement of ``Template'' and ``template'' -with the name of your new widget, using -the appropriate case, can be done. -.NH 3 -Public Header File -.LP -The public header file contains declarations that will be required by any -application module that needs to refer to the widget; whether to create -an instance of the class, to perform an -.PN XtSetValues -operation, or to call a public routine implemented by the widget class. -.LP -The contents of the Template public header file, -.Pn < X11/Template.h >, -are: -.de CB -.sp -.ps 9 -.nr PS 9 -.vs 10 -.Ds 0 -.in +.25i -.TA .25i 1.4i 2.4i 2.75i 3.5i -.ta .25i 1.4i 2.4i 2.75i 3.5i -.. -.de CE -.De -.\".in -.25i -.ps 11 -.nr PS 11 -.vs 13 -.. -.CB -.\".so ../../lib/Xaw/Template.h -#include <X11/copyright.h> - -/* XConsortium: Template.h,v 1.2 88/10/25 17:22:09 swick Exp $ */ -/* Copyright (c) X Consortium 1987, 1988 */ - -#ifndef _Template_h -#define _Template_h - -/**************************************************************** - * - * Template widget - * - ****************************************************************/ - -/* Resources: - - Name Class RepType Default Value - ---- ----- ------- ------------- - background Background Pixel XtDefaultBackground - border BorderColor Pixel XtDefaultForeground - borderWidth BorderWidth Dimension 1 - destroyCallback Callback Pointer NULL - height Height Dimension 0 - mappedWhenManaged MappedWhenManaged Boolean True - sensitive Sensitive Boolean True - width Width Dimension 0 - x Position Position 0 - y Position Position 0 - -*/ - -/* define any special resource names here that are not in <X11/StringDefs.h> */ - -#define XtNtemplateResource "templateResource" - -#define XtCTemplateResource "TemplateResource" - -/* declare specific TemplateWidget class and instance datatypes */ - -typedef struct _TemplateClassRec* TemplateWidgetClass; -typedef struct _TemplateRec* TemplateWidget; - -/* declare the class constant */ - -extern WidgetClass templateWidgetClass; - -#endif _Template_h - -.CE -.LP -.sp -You will notice that most of this file is documentation. The crucial -parts are the last 8 lines where macros for any private resource names -and classes are defined and where the widget class datatypes and class -record pointer are declared. -.LP -For the "WindowWidget", we want 2 drawing colors, a callback list for -user input and an -\fBXtNexposeCallback\fP callback list, and we will declare three -convenience procedures, so we need to add -.LP -.sp -.CB -/* Resources: - ... - callback Callback Callback NULL - drawingColor1 Color Pixel XtDefaultForeground - drawingColor2 Color Pixel XtDefaultForeground - exposeCallback Callback Callback NULL - font Font XFontStruct* XtDefaultFont - ... - */ - -#define XtNdrawingColor1 "drawingColor1" -#define XtNdrawingColor2 "drawingColor2" -#define XtNexposeCallback "exposeCallback" - -extern Pixel WindowColor1(\|/* Widget */\|); -extern Pixel WindowColor2(\|/* Widget */\|); -extern Font\ \ WindowFont(\|/* Widget */\|); -.CE -.LP -Note that we have chosen to call the input callback list by the generic -name, -.PN XtNcallback , -rather than a specific name. If widgets that define a single user-input -action all choose the same resource name then there is greater possibility -for an application to switch between widgets of different types. -.NH 3 -Private Header File -.LP -The private header file contains the complete declaration of the class -and instance structures for the widget and any additional private data -that will be required by anticipated subclasses of the widget. -Information in the private header file is normally hidden from the -application and is designed to be accessed only through other public -procedures; e.g. -.PN XtSetValues . -.LP -The contents of the Template private header file, -.Pn < X11/TemplateP.h >, -are: -.CB -.\".so ../../lib/Xaw/TemplateP.h -#include <X11/copyright.h> - -/* XConsortium: TemplateP.h,v 1.2 88/10/25 17:31:47 swick Exp $ */ -/* Copyright (c) X Consortium 1987, 1988 */ - -#ifndef _TemplateP_h -#define _TemplateP_h - -#include "Template.h" -/* include superclass private header file */ -#include <X11/CoreP.h> - -/* define unique representation types not found in <X11/StringDefs.h> */ - -#define XtRTemplateResource "TemplateResource" - -typedef struct { - int empty; -} TemplateClassPart; - -typedef struct _TemplateClassRec { - CoreClassPart core_class; - TemplateClassPart template_class; -} TemplateClassRec; - -extern TemplateClassRec templateClassRec; - -typedef struct { - /* resources */ - char* resource; - /* private state */ -} TemplatePart; - -typedef struct _TemplateRec { - CorePart core; - TemplatePart template; -} TemplateRec; - -#endif _TemplateP_h - -.CE -.LP -.sp -The private header file includes the private header file of its -superclass, thereby exposing the entire internal structure of the widget. -It may not always be advantageous to do this; your own project -development style will dictate the appropriate level of detail to expose -in each module. -.LP -The "WindowWidget" needs to declare two fields in its instance structure to -hold the drawing colors, a resource field for the font and a field for the -expose and user input callback lists: -.CB -typedef struct { - /* resources */ - Pixel color_1; - Pixel color_2; - XFontStruct* font; - XtCallbackList expose_callback; - XtCallbackList input_callback; - /* private state */ - /* (none) */ -} WindowPart; -.CE -.NH 3 -Widget Source File -.LP -The source code file implements the widget class itself. The unique -part of this file is the declaration and initialization of the -widget class record structure and the declaration of all resources and -action routines added by the widget class. -.LP -The contents of the Template implementation file, -.Pn < X11/Template.c >, -are: -.CB -.\".so ../../lib/Xaw/Template.c -#include <X11/copyright.h> - -/* XConsortium: Template.c,v 1.2 88/10/25 17:40:25 swick Exp $ */ -/* Copyright (c) X Consortium 1987, 1988 */ - -#include <X11/IntrinsicP.h> -#include <X11/StringDefs.h> -#include "TemplateP.h" - -static XtResource resources[] = { -#define offset(field) XtOffset(TemplateWidget, template.field) - /* {name, class, type, size, offset, default_type, default_addr}, */ - { XtNtemplateResource, XtCTemplateResource, XtRTemplateResource, sizeof(char*), - offset(resource), XtRString, "default" }, -#undef offset -}; - -static void TemplateAction(/* Widget, XEvent*, String*, Cardinal* */); - -static XtActionsRec actions[] = -{ - /* {name, procedure}, */ - {"template", TemplateAction}, -}; - -static char translations[] = -" <Key>: template(\|) \\n\\ -"; - -TemplateClassRec templateClassRec = { - { /* core fields */ - /* superclass */ (WidgetClass) &widgetClassRec, - /* class_name */ "Template", - /* widget_size */ sizeof(TemplateRec), - /* class_initialize */ NULL, - /* class_part_initialize */ NULL, - /* class_inited */ FALSE, - /* initialize */ NULL, - /* initialize_hook */ NULL, - /* realize */ XtInheritRealize, - /* actions */ actions, - /* num_actions */ XtNumber(actions), - /* resources */ resources, - /* num_resources */ XtNumber(resources), - /* xrm_class */ NULLQUARK, - /* compress_motion */ TRUE, - /* compress_exposure */ TRUE, - /* compress_enterleave */ TRUE, - /* visible_interest */ FALSE, - /* destroy */ NULL, - /* resize */ NULL, - /* expose */ NULL, - /* set_values */ NULL, - /* set_values_hook */ NULL, - /* set_values_almost */ XtInheritSetValuesAlmost, - /* get_values_hook */ NULL, - /* accept_focus */ NULL, - /* version */ XtVersion, - /* callback_private */ NULL, - /* tm_table */ translations, - /* query_geometry */ XtInheritQueryGeometry, - /* display_accelerator */ XtInheritDisplayAccelerator, - /* extension */ NULL - }, - { /* template fields */ - /* empty */ 0 - } -}; - -WidgetClass templateWidgetClass = (WidgetClass)&templateClassRec; - -.CE -The resource list for the "WindowWidget" might look like the following: -.CB -static XtResource resources[] = { -#define offset(field) XtOffset(WindowWidget, window.field) - /* {name, class, type, size, offset, default_type, default_addr}, */ - { XtNdrawingColor1, XtCColor, XtRPixel, sizeof(Pixel), - offset(color_1), XtRString, XtDefaultForeground }, - { XtNdrawingColor2, XtCColor, XtRPixel, sizeof(Pixel), - offset(color_2), XtRString, XtDefaultForeground }, - { XtNfont, XtCFont, XtRFontStruct, sizeof(XFontStruct*), - offset(font), XtRString, XtDefaultFont }, - { XtNexposeCallback, XtCCallback, XtRCallback, sizeof(XtCallbackList), - offset(expose_callback), XtRCallback, NULL }, - { XtNcallback, XtCCallback, XtRCallback, sizeof(XtCallbackList), - offset(input_callback), XtRCallback, NULL }, -#undef offset -}; -.CE -.LP -The user input callback will be implemented by an action procedure which -passes the event pointer as call_data. The action procedure -is declared as: -.CB -/* ARGSUSED */ -static void InputAction(w, event, params, num_params) - Widget w; - XEvent *event; - String *params; /* unused */ - Cardinal *num_params; /* unused */ -{ - XtCallCallbacks(w, XtNcallback, (caddr_t)event); -} - -static XtActionsRec actions[] = -{ - /* {name, procedure}, */ - {"input", InputAction}, -}; -.CE -.LP -and the default input binding will be to execute the input callbacks on -.PN KeyPress -and -.PN ButtonPress : -.LP -.CB -static char translations[] = -" <Key>: input(\|) \\n\\ - <BtnDown>: input(\|) \\ -"; -.CE -.LP -In the class record declaration and initialization, the only field that -is different from the Template is the expose procedure: -.CB -/* ARGSUSED */ -static void Redisplay(w, event, region) - Widget w; - XEvent *event; /* unused */ - Region region; -{ - XtCallCallbacks(w, XtNexposeCallback, (caddr_t)region); -} - -WindowClassRec windowClassRec = { - - ... - - /* expose */ Redisplay, -.CE -.LP -.sp -The "WindowWidget" will also declare three public procedures to return the -drawing colors and the font id, saving the application the effort of -constructing an argument list for a call to -.PN XtGetValues : -.LP -.CB -Pixel WindowColor1(w) - Widget w; -{ - return ((WindowWidget)w)->window.color_1; -} - -Pixel WindowColor2(w) - Widget w; -{ - return ((WindowWidget)w)->window.color_2; -} - -Font WindowFont(w) - Widget w; -{ - return ((WindowWidget)w)->window.font->fid; -} -.CE -.LP -The "WindowWidget" is now complete. The application can retrieve the two -drawing colors from the widget instance by calling either -.PN XtGetValues , -or the \fBWindowColor\fP functions. The actual window created for the -"WindowWidget" is available by calling the -.PN XtWindow -function. -.LP -To test the new ``WindowWidget'', you may substitute ``window'' for -``command'' in the sample program given in Section 2.7.3. -.TC diff --git a/xc/doc/specs/Xaw/block.awk b/xc/doc/specs/Xaw/block.awk deleted file mode 100644 index 0dd75f3f7..000000000 --- a/xc/doc/specs/Xaw/block.awk +++ /dev/null @@ -1,22 +0,0 @@ -BEGIN { - firstchar = "@"; - a["a"] = "A"; a["b"] = "B"; a["c"] = "C"; - a["d"] = "D"; a["e"] = "E"; a["f"] = "F"; - a["g"] = "G"; a["h"] = "H"; a["i"] = "I"; - a["j"] = "J"; a["k"] = "K"; a["l"] = "L"; - a["m"] = "M"; a["n"] = "N"; a["o"] = "O"; - a["p"] = "P"; a["q"] = "Q"; a["r"] = "R"; - a["s"] = "S"; a["t"] = "T"; a["u"] = "U"; - a["v"] = "V"; a["w"] = "W"; a["x"] = "X"; - a["y"] = "Y"; a["z"] = "Z"; -} - -{ - c = substr($2,2,1); - if (c >= "a" && c <= "z") - c = a[c]; - if (c != firstchar) - printf(".LB %s\n", c); - firstchar = c; - print; -} diff --git a/xc/doc/specs/Xaw/fixindex.awk b/xc/doc/specs/Xaw/fixindex.awk deleted file mode 100644 index e8849f3bd..000000000 --- a/xc/doc/specs/Xaw/fixindex.awk +++ /dev/null @@ -1,73 +0,0 @@ -BEGIN { - FS = ":"; - BD = "\\s+1\\fB"; - ED = "\\fP\\s-1"; -} - -NR == 1 { - if ($3 != "") - printf(".Ib \"%s\"\n", $2); - major = $2; - minor = $3; - if ($4 == "@DEF@") { - pagelist = BD $1 ED; - } - else { - pagelist = $1; - } - pageno = $1; - oldpageno = $1; - oldpagelist = ""; -} - -NR != 1 { - if ($2 == major && $3 == minor) # neither has changed - { - if ($1 != pageno) { # new page number, append - oldpageno = $1; - oldpagelist = pagelist; - if ($4 == "@DEF@") { - pagelist = pagelist ", " BD $1 ED; - } - else { - pagelist = pagelist ", " $1; - } - } - else { # old page, but check for def - if ($4 == "@DEF@") { - if (pageno == oldpageno) { - if (oldpagelist != "") - oldpagelist = oldpagelist ", " - } - pagelist = oldpagelist BD $1 ED; - } - } - } - else # one has changed - { - if (minor != "") # dump full record - printf(".I< \"%s\" \"%s\" \"%s\"\n", major, minor, pagelist); - else - printf(".I> \"%s\" \"%s\"\n", major, pagelist); - if ($4 == "@DEF@") { # restart pagelist - pagelist = BD $1 ED; - } - else { - pagelist = $1; - } - oldpagelist = ""; - oldpageno = $1; - if ($2 != major && $3 != "") # major has changed, minor not null - printf(".Ib \"%s\"\n", $2); - } - major = $2; - minor = $3; - pageno = $1; -} - -END { - if (minor != "") # dump full record - printf(".I< \"%s\" \"%s\" \"%s\"\n", major, minor, pagelist); - else - printf(".I> \"%s\" \"%s\"\n", major, pagelist); -} diff --git a/xc/doc/specs/Xaw/strings.mit b/xc/doc/specs/Xaw/strings.mit deleted file mode 100644 index 0c6c703bf..000000000 --- a/xc/doc/specs/Xaw/strings.mit +++ /dev/null @@ -1,10 +0,0 @@ -.\" $XConsortium: strings.mit,v 1.8 91/07/30 15:25:58 gildea Exp $ -.ds tk X Toolkit -.ds xT X Toolkit Intrinsics \(em C Language Interface -.ds xI Intrinsics -.ds xW Athena Widget Set \(em C Language Interface -.ds xL Xlib \(em C Language X Interface -.ds xC Inter-Client Communication Conventions Manual -.ds Rn 4 -.ds Vn 2.2 -.hw XtMake-Geometry-Request XtQuery-Geometry wid-get sub-class sub-classes diff --git a/xc/doc/specs/Xaw/strings.xaw b/xc/doc/specs/Xaw/strings.xaw deleted file mode 100644 index e3e01873b..000000000 --- a/xc/doc/specs/Xaw/strings.xaw +++ /dev/null @@ -1,714 +0,0 @@ -.\" $XConsortium: strings.xaw,v 1.25 94/05/01 20:33:37 gildea Exp $ -\" These macros are not associated with any widget. - -.de Rs \" Resource Conversion message -A converter is registered for this resource that will convert -the following strings: \fB\\$1\fP. -.. -.de Sk \" This is a resource of the associated sink. -.if 'AsciiText'\\$1' This is a resource of the associated sink. -.. -.de So \" This is a resource of the associated source. -.if 'AsciiText'\\$1' This is a resource of the associated source. -.. - -\" Object Resources -.de Dc \" Object destroyCallback -.IP destroyCallback 1.5i -All functions on this list are called when this widget is destroyed. -.. - -\" RectObj Resources -.de As \" RectObj ancestorSensitive -.IP ancestorSensitive 1.5i -The sensitivity state of the ancestors of this widget. A widget is -insensitive if either it or any of its ancestors is insensitive. -This resource should not be changed with \fBXtSetValues\fP, although it -may be queried. -.. -.de Bw \" RectObj borderWidth -.IP borderWidth 1.5i -The width of this widget's window border. -.. -.de Hw \" RectObj height and width -.IP height 1.5i -.br -.ns -.IP width 1.5i -The height and width of this widget in pixels. -.. -.de Se \" RectObj sensitive -.IP sensitive 1.5i -Whether or not the toolkit should pass user events to this widget. The -widget will not get input events if either \fBancestorSensitive\fP or -\fBsensitive\fP is \fBFalse\fP. -.. -.de Xy \" RectObj x and y -.IP x 1.5i -.br -.ns -.IP y 1.5i -The location of the upper left outside corner of this widget in its parent. -.. - -\" Core Resources - -.de Ac \" Core accelerators -.IP accelerators 1.5i -A list of event to action bindings to be executed by this widget, even -though the event occurred in another widget. (See the \fI\*(xT\fP for -details). -.. -.de Bg \" Core background -.ie 'Bold'\\$1' .IP \fBbackground\fP 1.5i -.el .IP background 1.5i -A pixel value which indexes the widget's colormap to derive the -background color of the widget's window. -.. -.de Gp \" Core backgroundPixmap -.IP backgroundPixmap 1.5i -The background pixmap of this widget's window. If this resource is set to -anything other than \fBXtUnspecifiedPixmap\fP, the pixmap specified will be -used instead of the background color. -.. -.de Bc \" Core borderColor -.IP borderColor 1.5i -A pixel value which indexes the widget's colormap to derive the border -color of the widget's window. -.. -.de Bp \" Core borderPixmap -.IP borderPixmap 1.5i -The border pixmap of this widget's window. If this resource is set to -anything other than \fBXtUnspecifiedPixmap\fP, the pixmap specified will be -used instead of the border color. -.. -.de Cm \" Core colormap -.IP colormap 1.5i -The colormap that this widget will use. -.. -.de Dp \" Core depth -.IP depth 1.5i -The depth of this widget's window. -.. -.de Mm \" Core mappedWhenManaged -.IP mappedWhenManaged 1.5i -If this resource is \fBTrue\fP, then the widget's window will -automatically be mapped by the Toolkit when it is realized and managed. -.. -.de Sc \" Core screen -.IP screen 1.5i -The screen on which this widget is displayed. This is not a settable -resource. -.. -.de Tr \" Core translations -.IP translations 1.5i -The event bindings associated with this widget. -.. - -\" Simple Widget Resource Definitions - -.de Cu \" Simple cursor -.ie 'Bold'\\$1' .IP \fBcursor\fP 1.5i -.el .IP cursor 1.5i -The image that will be displayed as the pointer cursor whenever it is in -this widget. The use of this resource is deprecated in favor -of \fBcursorName\fP. -.. -.de Cn \" Simple cursorName -.ie 'Bold'\\$1' .IP \fBcursorName\fP 1.5i -.el .IP cursorName 1.5i -The name of the symbol to use to represent the pointer cursor. This resource -will override the \fBcursor\fP resource if both are specified. (See 2.4.1) -.. -.de Ib \" Simple insensitiveBorder -.ie 'Bold'\\$1' .IP \fBinsensitiveBorder\fP 1.5i -.el .IP insensitiveBorder 1.5i -This pixmap will be tiled into the widget's border if the widget becomes -insensitive. -.. -.de In \" Simple international -.ie 'Bold'\\$1' .IP \fBinternational\fP 1.5i -.el .IP international 1.5i -This is a boolean flag, only settable at widget creation -time. A value of \fBfalse\fP signals the widget to use -pre-R6 internationalization (specifically, the lack thereof), -such as using fonts for displaying text, etc. A value of -\fBtrue\fP directs the widget to act in an internationalized -manner, such as utilizing font sets for displaying text, etc. -.. -.de Ix \" Simple international -.ie 'Bold'\\$1' .IP \fBinternational\fP 1.5i -.el .IP international 1.5i -This is a boolean flag, only settable at widget creation -time. While not utilized in this widget, it can and should -be checked by any subclasses that have behavior that -should vary with locale. -.. -.de Pf \" Simple pointerColor -.ie 'Bold'\\$1' .IP \fBpointerColor\fP 1.5i -.el .IP pointerColor 1.5i -A pixel value which indexes the widget's colormap to derive the foreground -color of the pointer symbol specified by the \fBcursorName\fP resource. -.. -.de Pb \" Simple pointerColorBackground -.ie 'Bold'\\$1' .IP \fBpointerColorBackground\fP 1.75i -.el .IP pointerColorBackground 1.75i -A pixel value which indexes the widget's colormap to derive the background -color of the pointer symbol specified by the \fBcursorName\fP resource. -.. - -\" Label Widget Resource Definitions - -.de Bm \" Label bitmap -.ie 'Bold'\\$1' .IP \fBbitmap\fP 1.5i -.el .IP bitmap 1.5i -A bitmap to display instead of the \fBlabel\fP. The default size of the -widget will be just large enough to contain the bitmap and the widget's -internal width and height. The resource converter for this resource -constructs bitmaps from the contents of files. (See \fBConverting -Bitmaps\fP for details.) If this bitmap is one bit deep then the 1's -will be rendered in the foreground color, and the 0's in the background -color. If \fBbitmap\fP has a depth greater than one, it is copied -directly into the window. -.. -.de Le \" Label encoding -.ie 'Bold'\\$1' .IP \fBencoding\fP 1.5i -.el .IP encoding 1.5i -The encoding method used by the value of the \fBlabel\fP resource. -The value may be \fBXawTextEncoding8bit\fP or \fBXawTextEncodingChar2b\fP. -When \fBinternational\fP is set to \fBtrue\fP this resource is not used. -.. -.de Lf \" Label font -.ie 'Bold'\\$1' .IP \fBfont\fP 1.5i -.el .IP font 1.5i -The text font to use when displaying the \fBlabel\fP, when the -\fBinternational\fP resource is \fBfalse\fP. -.. -.de Ls \" Label fontSet -.ie 'Bold'\\$1' .IP \fBfontSet\fP 1.5i -.el .IP fontSet 1.5i -The text font set to use when displaying the \fBlabel\fP, when the -\fBinternational\fP resource is \fBtrue\fP. -.. -.de Lg \" Label foreground -.ie 'Bold'\\$1' .IP \fBforeground\fP 1.5i -.el .IP foreground 1.5i -A pixel value which indexes the widget's colormap to derive the -foreground color of the widget's window. This color is also -used to render all 1's in a \fBbitmap\fP one plane deep. -.. -.de Ih \" Label internalHeight -.ie 'Bold'\\$1' .IP \fBinternalHeight\fP 1.5i -.el .IP internalHeight 1.5i -.br -.ns -.ie 'Bold'\\$1' .IP \fBinternalWidth\fP 1.5i -.el .IP internalWidth 1.5i -The minimum amount of space to leave between the graphic -and the vertical and horizontal edges of the window. -.. -.de Ju \" Label justify -.ie 'Bold'\\$1' .IP \fBjustify\fP 1.5i -.el .IP justify 1.5i -.IN "conversions" "Justify" -Specifies left, center, or right alignment of graphic within the -widget. This resource may be specified with the values -\fBXtJustifyLeft\fP, \fBXtJustifyCenter\fP, or \fBXtJustifyRight\fP. -.Rs "left, right, \fPand\fB center". -This resource only has noticeable effect when the width of the widget -is larger than necessary to display the graphic. Note that when the -graphic is a multi-line \fBlabel\fP, the longest line will obey this -justification while shorter lines will be left-justified with the longest -one. - -.. -.de La \" Label label -.ie 'Bold'\\$1' .IP \fBlabel\fP 1.5i -.el .IP label 1.5i -Specifies the text string to be displayed in the widget's window -if no bitmap is specified. The default is the name of this widget. -Irregardless of the value of \fBencoding\fP or \fBinternational\fP, -a single newline character (1 byte) will cause a line break. -.. -.de Ll \" Label leftBitmap -.ie 'Bold'\\$1' .IP \fBleftBitmap\fP 1.5i -.el .IP leftBitmap 1.5i -Specifies a bitmap to display to the left of the graphic in the widget's -window. -.. -.de Re \" Label resize -.ie 'Bold'\\$1' .IP \fBresize\fP 1.5i -.el .IP resize 1.5i -Specifies whether the widget should attempt to resize to its -preferred dimensions whenever its resources are modified with -\fBXtSetValues\fP. This attempt to resize may be denied by the parent -of this widget. The parent is always free to resize the widget -regardless of the state of this resource. -.. - -\" Command Widget Resource Definitions - -.de Cb \" Command callback -.ie 'Bold'\\$1' .IP \fBcallback\fP 1.5i -.el .IP callback 1.5i -A list of routines to be called when the \fBnotify\fP action is invoked. -.. -.de Cr \" Command cornerRoundPercent -.ie 'Bold'\\$1' .IP \fBcornerRoundPercent\fP 1.5i -.el .IP cornerRoundPercent 1.5i -When a \fBShapeStyle\fP of \fBroundedRectangle\fP is used, this -resource controls the radius of the rounded corner. The radius of the -rounded corners is specified as a percentage of the length of the -shortest side of the widget. -.. -.de Ht \" Command highlightThickness -.ie 'Bold'\\$1' .IP \fBhighlightThickness\fP 1.5i -.el .IP highlightThickness 1.5i -The thickness of the rectangle that is used to highlight the internal -border of this widget, alerting the user that it is ready to be -selected. The default value is 2 pixels if the \fBshapeStyle\fP is -\fBrectangle\fP, and 0 Pixels (no highlighting) otherwise. -.. -.de Ss \" Command shapeStyle -.ie 'Bold'\\$1' .IP \fBshapeStyle\fP 1.5i -.el .IP shapeStyle 1.5i -.IN "conversions" "ShapeStyle" -Nonrectangular widgets may be created using this resource. -Nonrectangular widgets are supported only on a server that supports the -\fBShape Extension\fP. If nonrectangular widgets are specified -for a server lacking this extension, the shape is ignored and the -widgets will be rectangular. The following shapes are currently -supported: \fBXmuShapeRectangle\fP, \fBXmuShapeOval\fP, -\fBXmuShapeEllipse\fP, and \fBXmuShapeRoundedRectangle\fP. -.Rs "rectangle, oval, ellipse, \fPand\fP roundedRectangle" -.. - -\" Composite Resources - -.de Ch \" Composite children -.IP children 1.5i -A list of all this composite widget's current children. -.. -.de Ip \" Composite insertPosition -.IP insertPosition 1.5i -A function which allows the application programmer to specify the position -of a new child. -.. -.de Nc \" Composite numChildren -.IP numChildren 1.5i -The number of children in this composite widget. -.. - -\" Form Resources - -.de Dd \" Form defaultDistance -.ie 'Bold'\\$1' .IP \fBdefaultDistance\fP 1.5i -.el .IP defaultDistance 1.5i -The default internal spacing for the children. This is -the default value for the constraint resources \fBhorizDistance\fP and -\fBvertDistance\fP. -.. - -\" Form Constraints - -.de Bt \" Form bottom, left, right, and top -.ie 'Bold'\\$1' .IP \fBbottom\fP 1.5i -.el .IP bottom 1.5i -.br -.ns -.ie 'Bold'\\$1' .IP \fBleft\fP 1.5i -.el .IP left 1.5i -.br -.ns -.ie 'Bold'\\$1' .IP \fBright\fP 1.5i -.el .IP right 1.5i -.br -.ns -.ie 'Bold'\\$1' .IP \fBtop\fP 1.5i -.el .IP top 1.5i -What to do with this edge of the child when the parent is resized. This -resource may be any \fBedgeType\fP. See \fBLayout Semantics\fP for -details. -.. -.de Fh \" Form fromHoriz and fromVert -.ie 'Bold'\\$1' .IP \fBfromHoriz\fP 1.5i -.el .IP fromHoriz 1.5i -.br -.ns -.ie 'Bold'\\$1' .IP \fBfromVert\fP 1.5i -.el .IP fromVert 1.5i -Which widget this child should be placed underneath (or to the right -of). If a value of NULL is specified then this widget will be positioned -relative to the edge of the parent. -.. -.de Hd \" Form horizDistance and vertDistance -.ie 'Bold'\\$1' .IP \fBhorizDistance\fP 1.5i -.el .IP horizDistance 1.5i -.br -.ns -.ie 'Bold'\\$1' .IP \fBvertDistance\fP 1.5i -.el .IP vertDistance 1.5i -The amount of space, in pixels, between this child and its left or -upper neighbor. -.. -.de Rl \" Form resizable -.ie 'Bold'\\$1' .IP \fBresizable\fP 1.5i -.el .IP resizable 1.5i -If this resource is \fBFalse\fP then the parent widget will ignore all -geometry request made by this child. The parent may still resize this -child itself, however. -.. - -.de Lt \" Form Section on Layout semantics -The \\$1 widget uses two different sets of layout semantics. One is -used when initially laying out the children. The other is used when -the \\$1 is resized. -.LP -The first layout method uses the \fBfromVert\fP and \fPfromHoriz\fP -.IN "fromVert" " -.IN "fromHoriz" "" -resources to place the children of the \\$1. A single pass is made -through the \\$1 widget's children in the order that they were created. -Each child is then placed in the \\$1 widget below or to the right of -the widget specified by the \fBfromVert\fP and \fBfromHoriz\fP resources. -The distance the new child is placed from its left or upper neighbor is -determined by the \fBhorizDistance\fP and \fBvertDistance\fP resources. -.IN "horizDistance" "" -.IN "vertDistance" "" -.IN "conversions" "Widget" -This implies some things about how the order of creation affects the -possible placement of the children. The Form widget registers a -string to widget converter which does not postpone conversion and -does not cache conversion results. -.LP -The second layout method is used when the \\$1 is resized. It does not -matter what causes this resize, and it is possible for a resize to -happen before the widget becomes visible (due to constraints imposed by -the parent of the \\$1). This layout method uses the \fBbottom\fP, -\fBtop\fP, \fBleft\fP, and \fBright\fP resources. These resources are -used to determine what will happen to each edge of the child when the -\\$1 is resized. If a value of \fBXawChain\fP\fI<something>\fP is -.IN "XawChain" "" -specified, the the edge of the child will remain a fixed distance from -the \fIchain\fP edge of the \\$1. For example if \fBXawChainLeft\fP is -specified for the \fBright\fP resource of a child then the right edge of -that child will remain a fixed distance from the left edge of the \\$1 -widget. If a value of \fBXawRubber\fP is specified, that edge will grow -.IN "XawRubber" "" -by the same percentage that the \\$1 grew. For instance if the \\$1 -grows by 50% the left edge of the child (if specified as \fBXawRubber\fP -will be 50% farther from the left edge of the \\$1). One must be very -careful when specifying these resources, for when they are specified -incorrectly children may overlap or completely occlude other children -when the \\$1 widget is resized. -.. - -\" Text Resources - -.de Af \" Text autoFill -.ie 'Bold'\\$1' .IP \fBautoFill\fP 1.5i -.el .IP autoFill 1.5i -If this resource is \fBTrue\fP the text widget will automatically break a line -when the user attempts to type into the right margin. The attribute has -no effect on files or text inserted into the text widget. It only -checks to see if the action should be taken when a user enters a new -character via the \fIinsert-character\fP action. -.. -.de Tm \" Text margin resources -.ie 'Bold'\\$1' .IP \fBbottomMargin\fP 1.5i -.el .IP bottomMargin 1.5i -.br -.ns -.ie 'Bold'\\$1' .IP \fBleftMargin\fP 1.5i -.el .IP leftMargin 1.5i -.br -.ns -.ie 'Bold'\\$1' .IP \fBrightMargin\fP 1.5i -.el .IP rightMargin 1.5i -.br -.ns -.ie 'Bold'\\$1' .IP \fBtopMargin\fP 1.5i -.el .IP topMargin 1.5i -The amount of space, in pixels, between the edge of the window -and the corresponding edge of the text within the window. If there is -a scrollbar active on this edge, then this is the space between the text and -the scrollbar. -.. -.de Tc \" Text displayCaret -.ie 'Bold'\\$1' .IP \fBdisplayCaret\fP 1.5i -.el .IP displayCaret 1.5i -Whether or not to display the text insert point. -.. -.de Td \" Text displayPosition -.ie 'Bold'\\$1' .IP \fBdisplayPosition\fP 1.5i -.el .IP displayPosition 1.5i -The position in the text buffer of the character that is currently -displayed in the upper left hand corner of the text display. -.. -.de Ti \" Text insertPosition -.ie 'Bold'\\$1' .IP \fBinsertPosition\fP 1.5i -.el .IP insertPosition 1.5i -This is the location of the insert point. It is expressed in -characters from the beginning of the file. The cursor will always be -forced to be on the screen. This resource may therefore be used to -scroll the text display to a certain character position. -.. -.de Tz \" Text resize -.ie 'Bold'\\$1' .IP \fBresize\fP 1.5i -.el .IP resize 1.5i -.IN "conversions" "XawTextResizeMode" -Controls whether or not the Text widget attempts to resize itself when -it is no longer able to display the full text buffer in the associated -window. Any attempt by the Text widget to resize itself is always -subject to the constraints imposed by its parent. The values -\fBXawtextResizeNever\fP, \fBXawtextResizeWidth\fP, -.IN "XawtextResizeNever" "" -.IN "XawtextResizeWidth" "" -\fBXawtextResizeHeight\fP, and \fBXawtextResizeBoth\fP are all -.IN "XawtextResizeHeight" "" -.IN "XawtextResizeBoth" "" -acceptable for this resource. -.Rs "never, height, width, \fPand\fB both" -.. -.de Ts \" Text scrollHorizontal and scrollVertical -.ie 'Bold'\\$1' .IP \fBscrollHorizontal\fP 1.5i -.el .IP scrollHorizontal 1.5i -.br -.ns -.ie 'Bold'\\$1' .IP \fBscrollVertical\fP 1.5i -.el .IP scrollVertical 1.5i -.IN "conversions" "XawTextScrollMode" -These resources control the placement of scrollbars on the left and -bottom edge of the text widget. These resources accept the -values \fBXawtextScrollAlways\fP, \fBXawtextScrollWhenNeeded\fP, and -.IN "XawtextScrollAlways" "" -.IN "XawtextScrollWhenNeeded" "" -\fBXawtextScrollNever\fP. -.IN "XawtextScrollNever" "" -.Rs "always, never, \fPand\fB whenNeeded" -If \fBXawtextScrollWhenNeeded\fP is specified, the appropriate scrollbar -will only appear when there is text in the buffer that is not able to -fit within the bounds of the current window. The scrollbar will -disappear when the text once again fits within the window. -.. -.de St \" Text selectTypes -.ie 'Bold'\\$1' .IP \fBselectTypes\fP 1.5i -.el .IP selectTypes 1.5i -Specifies the selection type array that is used when -multi-click is activated (see \fBText Selections for Application -Programmers\fP for details). This resource is used in place, and must -not be freed until the widget is destroyed. There is no -type converter registered for this resource, so it may not be set from -the resource manager. -.. -.de To \" Text Source and Sink Objects -.ie 'Bold'\\$1' .IP \fBtextSink\fP 1.5i -.el .IP textSink 1.5i -.br -.ns -.ie 'Bold'\\$1' .IP \fBtextSource\fP 1.5i -.el .IP textSource 1.5i -These are the TextSink or TextSource objects used by this widget. -.ie 'Bold'\\$1' When using the Text widget these MUST be set by the \ -application programmer. -.el \{\ -When \fBinternational\fP is set to \fBtrue\fP -the AsciiText widget initializes these resources to point -to an MultiSink and MultiSrc respectively. -When \fBinternational\fP is set to \fBfalse\fP -the AsciiText widget initializes these resources to point -to an AsciiSink and AsciiSrc respectively. -.\} -.. -.de Tw \" Text wrap -.ie 'Bold'\\$1' .IP \fBwrap\fP 1.5i -.el .IP wrap 1.5i -When the text in any one line is wider than the window there are several -possible actions. This resource allows the user to decide what will -happen. The accepted values for this resource are -\fBXawtextWrapNever\fP, \fBXawtextWrapLine\fP, and -.IN "XawtextWrapNever" "" -.IN "XawtextWrapLine" "" -\fBXawtextWrapWord\fP. With \fBXawtextWrapLine\fP all text -.IN "XawtextWrapWord" "" -.IN "WrapMode" -that is beyond the right edge of the window will be displayed on the -next line. With \fBXawtextWrapWord\fP the -same action occurs but the text is broken at a word boundary if -possible. If no wrapping is enabled then the text will extend off -the edge of the window, and a small rectangle will be painted in the -right margin to alert the user that this line is too long. -.Rs "never, word, \fPand\fB line" -.. -.de Tu \" Text unrealizeCallback -.ie 'Bold'\\$1' .IP \fBunrealizeCallback\fP 1.5i -.el .IP unrealizeCallback 1.5i -A list of callback functions which will be executed when the Text widget -is unrealized. -.. - -\" Text Sink Resources - -.de Sb \" TextSink background -.ie 'Bold'\\$1 .IP \fBbackground\fP 1.5i -.el .IP background 1.5i -A pixel value which indexes the Text widget's colormap to derive the -background color used by the text sink. -.. -.de Sg \" TextSink foreground -.ie 'Bold'\\$1' .IP \fBforeground\fP 1.5i -.el .IP foreground 1.5i -A pixel value which indexes the Text widget's colormap to derive the -foreground color used by the text sink. -.Sk \\$1 -.. - -\" Ascii Sink Resources - -.de Sd \" AsciiSink displayNonprinting -.ie 'Bold'\\$1' .IP \fBdisplayNonprinting\fP 1.5i -.el .IP displayNonprinting 1.5i -If this resource is \fBTrue\fP, the Text widget will display all -non-printable characters as the string \fI^@\fP. If \fBFalse\fP, the -Text widget -will just leave a blank space where a non-printable character exists -in the text buffer. -.Sk \\$1 -.. -.de Sh \" AsciiSink echo -.ie 'Bold'\\$1' .IP \fBecho\fP 1.5i -.el .IP echo 1.5i -Whether or not to echo characters to the screen. The buffer can still -be edited, but nothing is displayed. This mode can be useful for -entering passwords and other sensitive information. -.Sk \\$1 -.. -.de Sf \" AsciiSink font -.ie 'Bold'\\$1' .IP \fBfont\fP 1.5i -.el .IP font 1.5i -The text font to use when displaying the \fBstring\fP, when the -\fBinternational\fP resource is \fBfalse\fP. -.Sk \\$1 -.. -.de Sn \" MultiSink fontSet -.ie 'Bold'\\$1' .IP \fBfont\fP 1.5i -.el .IP font 1.5i -The text font set to use when displaying the \fBstring\fP, when the -\fBinternational\fP resource is \fBtrue\fP. -.Sk \\$1 -.. - -\" TextSrc Resources - -.de Oe \" TextSrc editType -.ie 'Bold'\\$1' .IP \fBeditType\fP 1.5i -.el .IP editType 1.5i -This is the type of editing that will be allowed in this text widget. -Legal values are \fBXawtextRead\fP, \fBXawtextEdit\fP, and -.IN "XawtextRead" "" -.IN "XawtextEdit" "" -\fBXawtextAppend\fP. -.IN "XawtextAppend" "" -.IN "conversions" "XawTextEditType" -.Rs "read, edit, \fPand\fB append" -.So \\$1 -.. - -\" AsciiSrc Resources - - -.de Oc \" AsciiSrc callback -.ie 'Bold'\\$1' .IP \fBcallback\fP 1.5i -.el .IP callback 1.5i -The callbacks registered on this resource will be called every time the -text buffer changes, after the text has been updated. -.So \\$1 -.. -.de Od \" AsciiSrc dataCompression -.ie 'Bold'\\$1' .IP \fBdataCompression\fP 1.5i -.el .IP dataCompression 1.5i -The AsciiSrc uses an algorithm that may cause the text buffer to grow -to about twice the size of the actual text over time, as the text is -edited. On systems where CPU cycles are cheaper than memory, it is helpful to -spend some extra time to compress this buffer back to its minimum size. -If this resource is \fBTrue\fP, the AsciiSrc will compress its data -to the minimum size required every time the text string is saved, or the -value of the string is queried. -.So \\$1 -.. -.de Ol \" AsciiSrc length -.ie 'Bold'\\$1' .IP \fBlength\fP 1.5i -.el .IP length 1.5i -If the \fBuseStringInPlace\fP resource is \fBFalse\fP this attribute has no -effect. If that resource is \fBTrue\fP, however, then the \fBlength\fP -resource specifies the length of the buffer passed to the text widget -in the \fBstring\fP resource. -.So \\$1 -.. -.de Op \" AsciiSrc pieceSize -.ie 'Bold'\\$1' .IP \fBpieceSize\fP 1.5i -.el .IP pieceSize 1.5i -This is the size of the internal chunks into which the text buffer is -broken down for memory management. The larger this value the less segmented -your memory will be, but the slower your editing will be. The text -widgets will always allocate a chunk of memory this size to stuff the -\fBstring\fP into, so when using small strings, having this buffer -large can waste memory. This resource has no effect if -\fBuseStringInPlace\fP is \fBTrue\fP. -.So \\$1 -.. -.de Os \" AsciiSrc string -.ie 'Bold'\\$1' .IP \fBstring\fP 1.5i -.el .IP string 1.5i -If \fBtype\fP is \fBXawAsciiString\fP then this string contains the -buffer to be displayed in the widget. If \fBtype\fP is -\fBXawAsciiFile\fP then the string contains the name of the file to be -displayed. This string is normally copied by the text widget into -internal memory, but may be used in place by setting the -\fBuseStringInPlace\fP resource. As of X11R4 this is a settable resource. -.So \\$1 -When the \fBstring\fP resource is queried, using \fBXtGetValues\fP, and -\fBuseStringInPlace\fP is false, the value returned is valid until -the next time the \fBstring\fP resource is queried, or until the application -writer calls \fBXawAsciiSrcFreeString\fP. If \fBuseStringInPlace\fP is -true, a pointer to the actual string is returned. See also section 5.6. -.. -.de Ot \" AsciiSrc type -.ie 'Bold'\\$1' .IP \fBtype\fP 1.5i -.el .IP type 1.5i -This resource may be either \fBXawAsciiString\fP or -\fBXawAsciiFile\fP. The value of this resource determines whether the -\fBstring\fP resource contains the name of a file to be opened or a buffer to -be displayed by the text widget. A converter has been registered for -this resource and accepts the values \fBstring\fP and \fBfile\fP. -.IN "conversions" "AsciiType" -.So \\$1 -.. -.de Ou \" AsciiSrc useStringInPlace -.ie 'Bold'\\$1' .IP \fBuseStringInPlace\fP 1.5i -.el .IP useStringInPlace 1.5i -Setting this resource to \fBTrue\fP will disable the memory management -provided by the Text widget, updating the \fBstring\fP resource in -place. Using the string in place can -be much more efficient for text widgets that display static data, or -where the programmer wishes to impose strict constraints on the -contents of the \fBstring\fP. When using the string in place be sure that: -the length of the string is specified by setting the \fBlength\fP resource, -the \fBtype\fP of the Text widget is \fBXawAsciiString\fP, and that -the \fBstring\fP exists for the lifetime of the text widget, or until it has -been reset. \fINote: Since the MultiSrc and AsciiSrc have different data -formats, use of this resource forces application code to be cognisant as to -which of the two is being used. Application programming is simplified when -use of this resource is avoided.\fP -.So \\$1 -.. -.\" .TB is used throughout this manual. Don't know what it is, -.\" but I'll guess "table bold". -.\" Note that I've also used it to set the size, rather than -.\" have (incorrect) commands sprinkled throughout the document. -.\" -gildea April 1994 -.de TB -.B -.ps 9 -.vs 11 -.. diff --git a/xc/doc/specs/Xaw/widg.idxmac.t b/xc/doc/specs/Xaw/widg.idxmac.t deleted file mode 100644 index e5a0527b8..000000000 --- a/xc/doc/specs/Xaw/widg.idxmac.t +++ /dev/null @@ -1,3 +0,0 @@ -.eh '\fBAthena Widget Set\fP''\fBX11, Release 6.4\fP' -.oh '\fBAthena Widget Set\fP''\fBX11, Release 6.4\fP' -.so index.pageno |