diff options
Diffstat (limited to 'libXaw/spec')
49 files changed, 11388 insertions, 0 deletions
diff --git a/libXaw/spec/AsciiSink b/libXaw/spec/AsciiSink new file mode 100644 index 000000000..56dc20ea6 --- /dev/null +++ b/libXaw/spec/AsciiSink @@ -0,0 +1,77 @@ +.\" $Xorg: AsciiSink,v 1.3 2000/08/17 19:42:25 cpqbld Exp $ +.LP +.NH 2 +Ascii Sink Object and Multi Sink Object +.LP +.XS + AsciiSink Object +.XE +.IN "AsciiSink object" "" "@DEF@" +.LP +.Ds 0 +.TA 2.0i +.ta 2.0i +Application Header file <X11/Xaw/AsciiSink.h> +.IN "AsciiSink.h" "" +Class Header file <X11/Xaw/AsciiSinkP.h> +.IN "AsciiSinkP.h" "" +Class asciiSinkObjectClass +.IN "asciiSinkObjectClass" "" +Class Name AsciiSink +.IN "AsciiSink object" "class name" +Superclass TextSink +.De +.LP +The AsciiSink or MultiSink object is used by a text widget to render the text. +Depending on its \fBinternational\fP resource, a +AsciiText widget will create one or the other of these when the AsciiText +itself is created. Both types are nearly identical; the following discussion +applies to both, with MultiSink differences noted only as they occur. +The AsciiSink +will display all printing characters in an 8 bit font, along with handling Tab +and Carriage Return. The name has been left as ``AsciiSink'' for compatibility. +\fIThe MultiSink will display all printing characters in a font set, along with +handling Tab and Carriage +Return.\fP The source object also reports the text window metrics to the +text widgets. +.NH 3 +Resources +.LP +When creating an AsciiSink object instance, the following resources are +retrieved from the argument list or from the resource database: +.LP +.IN "AsciiSink object" "resources" +.TS H +lw(1i) lw(1i) lw(1i) lw(.5i) lw(2i). +_ +.sp 3p +.TB +Name Class Type Notes Default Value +.sp 3p +_ +.TH +.R +.sp 3p +background Background Pixel XtDefaultBackground +destroyCallback Callback XtCallbackList NULL +displayNonprinting Output Boolean True +echo Output Boolean True +font Font XFontStruct* XtDefaultFont +fontSet FontSet XFontSet XtDefaultFontSet +foreground Foreground Pixel XtDefaultForeground +.sp 3p +_ +.TE +.Bg Bold +This resource is retrieved by the AsciiSink instead of being copied +from the Text widget. +.Dc +.Sd Bold +.Sh Bold +.IP \fBfont\fP 1.5i +The text font to use when displaying the \fBstring\fP. +(This resource is present in the AsciiSink, but not the MultiSink.) +.IP \fBfontSet\fP 1.5i +The text font set to use when displaying the \fBstring\fP. +(This resource is present in the MultiSink, but not the AsciiSink.) + diff --git a/libXaw/spec/AsciiSource b/libXaw/spec/AsciiSource new file mode 100644 index 000000000..19b976562 --- /dev/null +++ b/libXaw/spec/AsciiSource @@ -0,0 +1,208 @@ +.\" $Xorg: AsciiSource,v 1.3 2000/08/17 19:42:26 cpqbld Exp $ +.NH 2 +Ascii Source Object and Multi Source Object +.LP +.XS + AsciiSrc Object +.XE +.IN "AsciiSrc object" "" "@DEF@" +.LP +.Ds 0 +.TA 2.0i +.ta 2.0i +Application Header file <X11/Xaw/AsciiSrc.h> or <X11/Xaw/MultiSrc.h> +.IN "AsciiSrc.h" "" +Class Header file <X11/Xaw/AsciiSrcP.h> or <X11/Xaw/MultiSrcP.h> +.IN "AsciiSrcP.h" "" +Class asciiSrcObjectClass or multiSrcObjectClass +.IN "asciiSrcObjectClass" "" +Class Name AsciiSrc or MultiSrc +.IN "AsciiSrc object" "class name" +Superclass TextSource +.De +.LP +The AsciiSrc or MultiSrc object is used by a text widget to read the text from a +file or string in memory. Depending on its \fBinternational\fP resource, an +AsciiText widget will create one or the other of these when the AsciiText +itself is created. Both types are nearly identical; the following discussion +applies to both, with MultiSrc differences noted only as they occur. +.LP +The AsciiSrc understands all Latin1 characters plus Tab +and Carriage Return. \fIThe MultiSrc understands any set of character sets that +the underlying X implementation's internationalization handles.\fP +.LP +The AsciiSrc can be either of two types: \fBXawAsciiFile\fP +or \fBXawAsciiString\fP. +.LP +AsciiSrc objects of type \fBXawAsciiFile\fP read the text from a file and +store it +into an internal buffer. This buffer may then be modified, provided the +text widget is in the correct edit mode, just as if it were a source of +type \fBXawAsciiString\fP. Unlike R3 and earlier versions of the AsciiSrc, +it is now possible to specify an editable disk source. The file is not +updated, however, until a call to \fBXawAsciiSave\fP is made. When the +source is in this mode the \fBuseStringInPlace\fP resource is ignored. +.LP +AsciiSrc objects of type \fBXawAsciiString\fP have the text buffer +implemented as a string. +\fIMultiSrc objects of type \fBXawAsciiString\fP have the text buffer +implemented as a wide character string.\fP +The string owner is responsible for allocating and managing storage for the +string. +.LP +In the default case for AsciiSrc objects of type \fBXawAsciiString\fP, +the resource \fBuseStringInPlace\fP is false, +and the widget owns the string. The initial value of the +string resource, and any update made by the application +programmer to the string resource with \fBXtSetValues\fP, is copied +into memory private to the widget, and managed internally by the widget. +The application writer +does not need to worry about running out of buffer space +(subject to the total memory available to the application). +The performance does not decay linearly as the buffer grows +large, as is necessarily the case when the text buffer is used +in place. The application writer must use \fBXtGetValues\fP to +determine the contents of the text buffer, which will return +a copy of the widget's text buffer as +it existed at the time of the \fBXtGetValues\fP call. This copy +is not affected by subsequent updates to the text buffer, i.e., +it is not updated as the user types input into the text buffer. +This copy is freed upon the next call to XtGetValues to +retrieve the string resource; however, to conserve memory, +there is a convenience routine, \fBXawAsciiSourceFreeString\fP, allowing the +application programmer to direct the widget to free the copy. +.LP +When the resource \fBuseStringInPlace\fP is true and the AsciiSrc object +is of type \fBXawAsciiString\fP, the application +is the string owner. The widget will take the value +of the string resource as its own text buffer, and the \fBlength\fP +resource indicates the buffer size. In this case +the buffer contents change as the user types at the widget; +it is not necessary to call \fBXtGetValues\fP on the string +resource to determine the contents of the buffer\*-it will +simply return the address of the application's implementation +of the text buffer. +.NH 3 +Resources +.LP +When creating an AsciiSrc object instance, the following resources are +retrieved from the argument list or from the resource database: +.LP +.IN "AsciiSrc object" "resources" +.TS H +lw(1i) lw(1i) lw(1i) lw(.5i) lw(2i). +_ +.sp 3p +.TB +Name Class Type Notes Default Value +.sp 3p +_ +.TH +.R +.sp 3p +callback Callback XtCallbackList NULL +dataCompression DataCompression Boolean True +destroyCallback Callback Callback NULL +editType EditType EditMode XawtextRead +length Length Int A length of \fBstring\fP +pieceSize PieceSize Int BUFSIZ +string String String NULL +type Type AsciiType XawAsciiString +useStringInPlace UseStringInPlace Boolean False +.sp 3p +_ +.TE +.Oc Bold +.Dc +.Od Bold +.Oe +.Ol Bold +.Op Bold +.Os Bold +.Ot Bold +.Ou Bold +.NH 3 +Convenience Routines +.LP +The AsciiSrc has a few convenience routines that allow the +application programmer quicker or easier access to some of the +commonly used functionality of the AsciiSrc. +.NH 4 +Conserving Memory +.LP +When the AsciiSrc widget is not in \fBuseStringInPlace\fP mode +space must be allocated whenever the file is saved, or the string is +requested with a call to \fBXtGetValues\fP. This memory is allocated on the +fly, and remains valid until the next time a string needs to be allocated. +You may save memory by freeing this string as soon as you are done +with it by calling \fBXawAsciiSourceFreeString\fP. +.FD 0 +void XawAsciiSourceFreeString(\fIw\fP) +.IN "XawAsciiSourceFreeString" "" @DEF@ +.br +Widget \fIw\fP; +.FN +.IP \fIw\fP 1i +Specifies the AsciiSrc object. +.LP +This function will free the memory that contains the string pointer returned +by \fBXtGetValues\fP. This will normally happen automatically when +the next call to \fBXtGetValues\fP occurs, or when the widget is destroyed. +.NH 4 +Saving Files +.LP +To save the changes made in the current text source into a file use +\fBXawAsciiSave\fP. +.FD 0 +Boolean XawAsciiSave(\fIw\fP) +.IN "XawAsciiSave" "" @DEF@ +.br +Widget \fIw\fP; +.FN +.IP \fIw\fP 1i +Specifies the AsciiSrc object. +.LP +\fBXawAsciiSave\fP returns \fBTrue\fP if the save was successful. +It will update the file named in the \fBstring\fP resource. +If the buffer has not been changed, no action will be taken. This function +only works on an AsciiSrc of type \fBXawAsciiFile\fP. +.LP +.sp 1 +To save the contents of the current text buffer into a named file use +\fBXawAsciiSaveAsFile\fP. +.FD 0 +Boolean XawAsciiSaveAsFile(\fIw\fP, \fIname\fP) +.IN "XawAsciiSaveAsFile" "" @DEF@ +.br +Widget \fIw\fP; +.br +String \fIname\fP; +.FN +.IP \fIw\fP 1i +Specifies the AsciiSrc object. +.IP \fIname\fP 1i +The name of the file to save the current buffer into. +.LP +This function returns \fBTrue\fP if the save was successful. +\fBXawAsciiSaveAsFile\fP will work with a buffer of either type +\fBXawAsciiString\fP or type \fBXawAsciiFile\fP. +.NH 4 +Seeing if the Source has Changed +.LP +To find out if the text buffer in an AsciiSrc object has changed +since the last time it was saved with \fBXawAsciiSave\fP or queried +.IN "XawAsciiSave" "" +use \fBXawAsciiSourceChanged\fP. +.FD 0 +Boolean XawAsciiSourceChanged(\fIw\fP) +.IN "XawAsciiSourceChanged" "" @DEF@ +.br +Widget \fIw\fP; +.FN +.IP \fIw\fP 1i +Specifies the AsciiSrc object. +.LP +This function will return \fBTrue\fP if the source has changed since +the last time it was saved or queried. The internal change flag is +reset whenever the string is queried via \fBXtGetValues\fP or the +buffer is saved via \fBXawAsciiSave\fP. diff --git a/libXaw/spec/AsciiText b/libXaw/spec/AsciiText new file mode 100644 index 000000000..815e0e162 --- /dev/null +++ b/libXaw/spec/AsciiText @@ -0,0 +1,166 @@ +.\" $Xorg: AsciiText,v 1.3 2000/08/17 19:42:26 cpqbld Exp $ +.NH 2 +Ascii Text Widget +.LP +.XS + AsciiText Widget +.XE +.IN "AsciiText widget" "" "@DEF@" +.LP +.Ds 0 +.TA 2.0i +.ta 2.0i +Application Header file <X11/Xaw/AsciiText.h> +.IN "AsciiText.h" "" +ClassHeader file <X11/Xaw/AsciiTextP.h> +.IN "AsciiTextP.h" "" +Class asciiTextWidgetClass +.IN "asciiTextWidgetClass" "" +Class Name Text +.IN "AsciiText widget" "class name" +Superclass Text +Sink Name textSink +Source Name textSource +.De +.sp 1 +.LP +For the ease of internationalization, the AsciiText widget class name has not +been changed, although it is actually able to support non-ASCII locales. +The AsciiText widget is really a collection of smaller parts. It +includes the Text widget itself, a ``Source'' (which supports memory management), +and a ``Sink'' (which handles the display). There are currently two supported +sources, the AsciiSrc and MultiSrc, and two supported sinks, the AsciiSink and +.IN "AsciiSrc object" "" +.IN "AsciiSink object" "" +.IN "MultiSrc object" "" +.IN "MultiSink object" "" +MultiSink. Some of +the resources listed below are not actually resources of the +AsciiText, but belong to the associated source or sink. This is +is noted in the explanation of each resource where it applies. When +specifying these resources in a resource file it is necessary to use +\fI*AsciiText*resource_name\fP instead of +\fI*AsciiText.resource_name\fP, since they actually belong to the +children of the AsciiText widget, and not the AsciiText widget itself. +However, these resources may be set directly on the AsciiText widget at +widget creation time, or via \fBXtSetValues\fP. +.NH 3 +Resources +.LP +When creating an AsciiText widget instance, the following resources are +retrieved from the argument list or from the resource database: +.LP +.IN "AsciiText widget" "resources" +.TS H +expand; +lw(1i) lw(1i) lw(1.1i) lw(.5i) lw(1.9i). +_ +.sp 3p +.TB +Name Class Type Notes Default Value +.sp 3p +_ +.TH +.R +.sp 3p +accelerators Accelerators AcceleratorTable NULL +ancestorSensitive AncestorSensitive Boolean D True +autoFill AutoFill Boolean False +background Background Pixel XtDefaultBackground +backgroundPixmap Pixmap Pixmap XtUnspecifiedPixmap +borderColor BorderColor Pixel XtDefaultForeground +borderPixmap Pixmap Pixmap XtUnspecifiedPixmap +borderWidth BorderWidth Dimension 1 +bottomMargin Margin Position 2 +callback Callback XtCallbackList NULL +colormap Colormap Colormap Parent's Colormap +cursor Cursor Cursor XC_xterm +cursorName Cursor String NULL +dataCompression DataCompression Boolean True +depth Depth int C Parent's Depth +destroyCallback Callback XtCallbackList NULL +displayCaret Output Boolean True +displayNonprinting Output Boolean True +displayPosition TextPosition XawTextPosition 0 +echo Output Boolean True +editType EditType XawTextEditType XawtextRead +font Font XFontStruct* XtDefaultFont +fontSet FontSet XFontSet XtDefaultFontSet +foreground Foreground Pixel XtDefaultForeground +height Height Dimension A Font height + margins +insensitiveBorder Insensitive Pixmap GreyPixmap +insertPosition TextPosition int 0 +international International Boolean C False +leftMargin Margin Dimension 2 +length Length int A length of \fBstring\fP +mappedWhenManaged MappedWhenManaged Boolean True +pieceSize PieceSize XawTextPosition BUFSIZ +pointerColor Foreground Pixel XtDefaultForeground +pointerColorBackground Background Pixel XtDefaultBackground +resize Resize XawTextResizeMode XawtextResizeNever +rightMargin Margin Position 2 +screen Screen Screen R Parent's Screen +scrollHorizontal Scroll XawTextScrollMode XawtextScrollNever +scrollVertical Scroll XawTextScrollMode XawtextScrollNever +selectTypes SelectTypes XawTextSelectType* See above +sensitive Sensitive Boolean True +string String String NULL +textSink TextSink Widget An AsciiSink +textSource TextSource Widget An AsciiSrc +topMargin Margin Position 2 +translations Translations TranslationTable See above +type Type XawAsciiType XawAsciiString +useStringInPlace UseStringInPlace Boolean False +width Width Dimension 100 +wrap Wrap WrapMode XawtextWrapNever +x Position Position 0 +y Position Position 0 +.sp 3p +_ +.TE +.Ac +.As +.Af +.Bg +.Gp +.Bc +.Bp +.Bw +.Tm +.Oc AsciiText +.Cm +.Cu +.Cn +.Od AsciiText +.Dp +.Dc +.Tc +.Sd AsciiText +.Td +.Oe AsciiText +.Sh AsciiText +.Sf AsciiText +.Sn AsciiText +.Sg AsciiText +.Hw +.Ib +.Ti +.Ol AsciiText +.Mm +.Pf +.Pb +.Op AsciiText +.Tz +.Sc +.Ts +.St +.Se +.Os AsciiText +.To +.Tr +.Ot AsciiText +.Ou AsciiText +.Tw +.Xy + + diff --git a/libXaw/spec/Box b/libXaw/spec/Box new file mode 100644 index 000000000..22bfe39b1 --- /dev/null +++ b/libXaw/spec/Box @@ -0,0 +1,139 @@ +.\" $Xorg: Box,v 1.3 2000/08/17 19:42:26 cpqbld Exp $ +.NH 2 +Box Widget +.LP +.XS + Box Widget +.XE +.IN "Box widget" "" "@DEF@" +.Ds 0 +.TA 2.0i +.ta 2.0i +.sp +Application Header file <X11/Xaw/Box.h> +.IN "Box.h" "" +Class Header file <X11/Xaw/BoxP.h> +.IN "BoxP.h" "" +Class boxWidgetClass +.IN "boxWidgetClass" "" +Class Name Box +.IN "Box widget" "class name" +Superclass Composite +.sp +.De +.LP +The Box widget provides geometry management of arbitrary widgets in a +box of a specified dimension. The children are rearranged when +resizing events occur either on the Box or its children, or when +children are managed or unmanaged. The Box widget always attempts to +pack its children as tightly as possible within the geometry allowed by +its parent. +.LP +Box widgets are commonly used to manage a related set of buttons and +are often called ButtonBox widgets, but the children are not +limited to buttons. The Box's children are arranged on a background that +has its own specified dimensions and color. +.NH 3 +Resources +.LP +When creating a Box widget instance, the following resources are +retrieved from the argument list or from the resource database: +.LP +.IN "Box widget" "resources" +.TS H +expand; +lw(1i) lw(1i) lw(1i) lw(.5i) lw(2i). +_ +.sp 3p +.TB +Name Class Type Notes Default Value +.sp 3p +_ +.TH +.R +.sp 3p +accelerators Accelerators AcceleratorTable NULL +ancestorSensitive AncestorSensitive Boolean D True +background Background Pixel XtDefaultBackground +backgroundPixmap Pixmap Pixmap XtUnspecifiedPixmap +borderColor BorderColor Pixel XtDefaultForeground +borderPixmap Pixmap Pixmap XtUnspecifiedPixmap +borderWidth BorderWidth Dimension 1 +children ReadOnly WidgetList R NULL +colormap Colormap Colormap Parent's Colormap +depth Depth int C Parent's Depth +destroyCallback Callback XtCallbackList NULL +height Height Dimension A see \fBLayout Semantics\fP +hSpace HSpace Dimension 4 +mappedWhenManaged MappedWhenManaged Boolean True +numChildren ReadOnly Cardinal R 0 +orientation Orientation Orientation XtorientVertical +screen Screen Screen R Parent's Screen +sensitive Sensitive Boolean True +vSpace VSpace Dimension 4 +translations Translations TranslationTable NULL +width Width Dimension A see \fBLayout Semantics\fP +x Position Position 0 +y Position Position 0 +.sp 3p +_ +.TE +.Ac +.As +.Bg +.Gp +.Bc +.Bp +.Bw +.Ch +.Cm +.Dp +.Dc +.Hw +.IP \fBhSpace\fP 1.5i +.br +.ns +.IP \fBvSpace\fP 1.5i +The amount of space, in pixels, to leave between the children. This +resource specifies the amount of space left between the outermost +children and the edge of the box. +.Mm +.Nc +.IP \fBorientation\fP 1.5i +Specifies whether the preferred shape of the box (i.e. the result +returned by the query_geometry class method) is tall and narrow +\fBXtorientVertical\fP or short and wide \fPXtorientHorizontal\fP. +.IN "XtorientVertical" "" +.IN "XtorientHorizontal" "" +.IN "conversions" "Orientation" +When the Box is a child of a parent which enforces width constraints, it +is usually better to specify \fBXtorientVertical\fP (the default). +When the parent enforces height constraints, it is usually better to +specify \fBXtorientHorizontal\fP. +.Rs "horizontal \fPand\fB vertical" +.Sc +.Se +.Tr +.Xy +.NH 3 +Layout Semantics +.IN "Box widget" "layout semantics" +.LP +Each time a child is managed or unmanaged, the Box widget will attempt +to reposition the remaining children to compact the box. Children are +positioned in order left to right, top to bottom. The packing +algorithm used depends on the \fBorientation\fP of the Box. +.IP \fBXtorientVertical\fP 1.5i +.IN "XtorientVertical" "" @DEF@ +When the next child does not fit on the current row, a new row is +started. If a child is wider than the width of the box, the box will +request a larger width from its parent and will begin the layout +process from the beginning if a new width is granted. +.IP \fBXtorientHorizontal\fP 1.5i +.IN "XtorientHorizontal" "" @DEF@ +When the next child does not fit on the current row, the Box widens if +possible (so as to keep children on a single row); otherwise a new row is +started. +.LP +After positioning all children, the Box widget attempts to shrink its +own size to the minimum dimensions required for the layout. diff --git a/libXaw/spec/CH1 b/libXaw/spec/CH1 new file mode 100644 index 000000000..b392a7012 --- /dev/null +++ b/libXaw/spec/CH1 @@ -0,0 +1,411 @@ +.\" $Xorg: CH1,v 1.3 2000/08/17 19:42:26 cpqbld Exp $ +.ps 11 +.nr PS 11 +.ds LH \fBAthena Widget Set\fP +.ds CH +.ds RH \fB\*(xV\fP +.bp 1 +.af PN 1 +\& +.sp 1 +.ce 3 +\s+1\fBChapter 1\fP\s-1 + +\s+1\fBAthena Widgets and The Intrinsics\fP\s-1 +.sp 2 +.nr H1 1 +.if \n(GS .nr nh*hl 1 +.nr H2 0 +.nr H3 0 +.nr H4 0 +.nr H5 0 +.LP +.XS +Chapter 1 \- Athena Widgets and The \*(xI +.XE +The X Toolkit is made up of two distinct pieces, the Xt \*(xI and a +widget set. The Athena widget set is a sample implementation of a +widget set built upon the \*(xI. In the \*(tk, a widget is the +combination of an X window or subwindow and its associated input and +output semantics. +.LP +Because the \*(xI provide the same basic functionality to all widget +sets it may be possible to use widgets from the Athena widget set with +other widget sets based upon the \*(xI. Since widget sets may also +implement private protocols, all functionality may not be available when +mixing and matching widget sets. For information about the \*(xI, see +the \fI\*(xT\fP. +.LP +The Athena widget set is a library package layered on top of the \*(xI +and Xlib that provides a set of user interface tools sufficient to build +a wide variety of applications. This layer extends the basic +abstractions provided by X and provides the next layer of functionality +primarily by supplying a cohesive set of sample widgets. Although the +\*(xI are a Consortium standard, there is no standard widget set. +.LP +To the extent possible, the \*(xI are "policy-free". The application +environment and widget set, not the \*(xI, define, implement, and +enforce: +.IP \(bu 5 +Policy +.IP \(bu 5 +Consistency +.IP \(bu 5 +Style +.LP +Each individual widget implementation defines its own policy. The \*(tk +design allows for, but does not necessarily encourage, the free mixing +of radically differing widget implementations. +.NH 2 +Introduction to the \*(tk +.LP +.XS + Introduction to the \*(tk +.XE +.IN "introduction" "" "@DEF@" +The \*(tk provides tools that simplify the design of +application user interfaces in the X Window System programming environment. +It assists application programmers by providing a set of common +underlying user-interface functions. It also lets widget programmers +modify existing widgets, by subclassing, or add new widgets. By using +the \*(tk in their applications, programmers can present a similar +user interface across applications to all workstation users. +.LP +The \*(tk consists of: +.IP \(bu 5 +A set of \*(xI functions for building widgets +.IP \(bu 5 +An architectural model for constructing widgets +.IP \(bu 5 +A widget set for application programming +.LP +While the majority of the \*(xI functions are intended +for the widget programmer, +a subset of the \*(xI functions are to be used by application programmers +(see \fI\*(xT\fP). +The architectural model lets the widget programmer design new widgets +by using the \*(xI and by combining other widgets. +The application interface layers built on top of the \*(tk include a +coordinated set of widgets and composition policies. +Some of these widgets and policies are specific to a single +application domain, and others are common to a variety of +applications. +.LP +The remainder of this chapter discusses the \*(tk and Athena widget set: +.IP \(bu 5 +Terminology +.IP \(bu 5 +Model +.IP \(bu 5 +Conventions used in this manual +.IP \(bu 5 +Format of the Widget Reference Chapters +.NH 2 +Terminology +.LP +.XS + Terminology +.XE +.LP +In addition to the terms already defined for X programming (see \fI\*(xL\fP), +the following terms are specific to the \*(xI and Athena widget set +and used throughout this document. +.LP +\fBApplication programmer\fP +.IN "application programmer" "" "@DEF@" +.IP +A programmer who uses the \*(tk to produce an application user interface. +.LP +\fBChild\fP +.IN "child" "" "@DEF" +.IP +A widget that is contained within another "parent" widget. +.LP +\fBClass\fP +.IN "class" "" "@DEF@" +.IP +The general group to which a specific object belongs. +.LP +\fBClient\fP +.IN "client" "" "@DEF@" +.IP +A function that uses a widget in an application or for composing +other widgets. +.LP +\fBFullName\fP +.IN "FullName" "" "@DEF" +.IP +The name of a widget instance appended to the full name of its parent. +.LP +\fBInstance\fP +.IN "instance" "" "@DEF@" +.IP +A specific widget object as opposed to a general widget class. +.LP +\fBMethod\fP +.IN "method" "" "@DEF@" +.IP +A function or procedure implemented by a widget class. +.LP +\fBName\fP +.IN "name" "widget" "@DEF@" +.IP +The name that is specific to an instance of a widget for a given client. +This name is specified at creation time and cannot be modified. +.LP +\fBObject\fP +.IN "object" "" "@DEF@" +.IP +A data abstraction consisting of private data and private and public +functions that operate on the private data. +Users of the abstraction can interact with the object only through calls +to the object's public functions. +In the \*(tk, +some of the object's public functions are called directly by the application, +while others are called indirectly when the application calls the common +\*(xI functions. +In general, if a function is common to all widgets, +an application uses a single \*(xI function to invoke the function for all +types of widgets. +If a function is unique to a single widget type, +the widget exports the function. +.LP +\fBParent\fP +.IN "parent" "" "@DEF@" +.IP +A widget that contains at least one other ("child") widget. +A parent widget is also known as a composite widget. +.LP +\fBResource\fP +.IN "resource" "" "@DEF@" +.IP +A named piece of data in a widget that can be set by a client, +by an application, or by user defaults. +.LP +\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/libXaw/spec/CH2 b/libXaw/spec/CH2 new file mode 100644 index 000000000..9e6c17a8a --- /dev/null +++ b/libXaw/spec/CH2 @@ -0,0 +1,1103 @@ +.\" $Xorg: CH2,v 1.3 2000/08/17 19:42:26 cpqbld 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/libXaw/spec/CH3.intro b/libXaw/spec/CH3.intro new file mode 100644 index 000000000..9040e02d5 --- /dev/null +++ b/libXaw/spec/CH3.intro @@ -0,0 +1,67 @@ +.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/libXaw/spec/CH4.intro b/libXaw/spec/CH4.intro new file mode 100644 index 000000000..c11e42547 --- /dev/null +++ b/libXaw/spec/CH4.intro @@ -0,0 +1,87 @@ +.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/libXaw/spec/CH5.intro b/libXaw/spec/CH5.intro new file mode 100644 index 000000000..69230c0ad --- /dev/null +++ b/libXaw/spec/CH5.intro @@ -0,0 +1,292 @@ +.\" $Xorg: CH5.intro,v 1.3 2000/08/17 19:42:26 cpqbld 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/libXaw/spec/CH6.intro b/libXaw/spec/CH6.intro new file mode 100644 index 000000000..530f2f7f9 --- /dev/null +++ b/libXaw/spec/CH6.intro @@ -0,0 +1,84 @@ +.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/libXaw/spec/CH7.intro b/libXaw/spec/CH7.intro new file mode 100644 index 000000000..7aaa1896b --- /dev/null +++ b/libXaw/spec/CH7.intro @@ -0,0 +1,99 @@ +.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/libXaw/spec/Command b/libXaw/spec/Command new file mode 100644 index 000000000..13dac468b --- /dev/null +++ b/libXaw/spec/Command @@ -0,0 +1,205 @@ +.\" $Xorg: Command,v 1.3 2000/08/17 19:42:26 cpqbld 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/libXaw/spec/Dialog b/libXaw/spec/Dialog new file mode 100644 index 000000000..d14bca0b4 --- /dev/null +++ b/libXaw/spec/Dialog @@ -0,0 +1,280 @@ +.\" $Xorg: Dialog,v 1.3 2000/08/17 19:42:26 cpqbld 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/libXaw/spec/Form b/libXaw/spec/Form new file mode 100644 index 000000000..9ada171dd --- /dev/null +++ b/libXaw/spec/Form @@ -0,0 +1,200 @@ +.\" $Xorg: Form,v 1.3 2000/08/17 19:42:26 cpqbld 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 a 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/libXaw/spec/Grip b/libXaw/spec/Grip new file mode 100644 index 000000000..cdbcb0ee6 --- /dev/null +++ b/libXaw/spec/Grip @@ -0,0 +1,157 @@ +.\" $Xorg: Grip,v 1.3 2000/08/17 19:42:26 cpqbld 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/libXaw/spec/Label b/libXaw/spec/Label new file mode 100644 index 000000000..bbf4ce44a --- /dev/null +++ b/libXaw/spec/Label @@ -0,0 +1,122 @@ +.\" $Xorg: Label,v 1.3 2000/08/17 19:42:27 cpqbld 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/libXaw/spec/List b/libXaw/spec/List new file mode 100644 index 000000000..1b64aaaf5 --- /dev/null +++ b/libXaw/spec/List @@ -0,0 +1,341 @@ +.\" $Xorg: List,v 1.3 2000/08/17 19:42:27 cpqbld 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/libXaw/spec/Makefile.am b/libXaw/spec/Makefile.am new file mode 100644 index 000000000..9e16f9797 --- /dev/null +++ b/libXaw/spec/Makefile.am @@ -0,0 +1,96 @@ +# +# Copyright 2009 Sun Microsystems, Inc. All rights reserved. +# +# Permission to use, copy, modify, distribute, and sell this software and its +# documentation for any purpose is hereby granted without fee, provided that +# the above copyright notice appear in all copies and that both that +# copyright notice and this permission notice appear in supporting +# documentation. +# +# The above copyright notice and this permission notice shall be included +# in all copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +# OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +# IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR +# OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +# ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +# OTHER DEALINGS IN THE SOFTWARE. +# +# Except as contained in this notice, the name of the copyright holders 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 copyright holders. +# + +# Based on xc/doc/specs/Xaw/Makefile from X11R6.9 + +XDOCMACROS = macros.t +XIDXMACROS = indexmacros.t +EVERYWHERE = $(XDOCMACROS) 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 + +spec_sources = \ + $(EVERYWHERE) TPage_Credits \ + $(CHAPTER1) $(CHAPTER2) $(CHAPTER3) $(CHAPTER4) \ + $(CHAPTER5) $(CHAPTER6) $(CHAPTER7) + +spec_input = $(spec_sources:%=$(srcdir)/%) + +EXTRA_DIST = $(spec_sources) $(XIDXMACROS) block.awk fixindex.awk widg.idxmac.t + +if BUILD_DOCS +doc_DATA = widgets.ps widgets.index.ps widgets.txt widgets.html + +CLEANFILES = $(doc_DATA) +MOSTLYCLEANFILES = index.* + +GROFF_DEFS = -dxV="$(PACKAGE_STRING)" +GROFF_FLAGS = -t -ms $(GROFF_DEFS) + +widgets.ps: $(spec_input) + -$(AM_V_GEN) $(GROFF) -Tps $(GROFF_FLAGS) $(spec_input) \ + 2> index.raw > $@ + @if grep '^[^1-9.]' index.raw | grep -v warning; then exit 1; \ + else test $$? -le 1; fi + +widgets.txt: $(spec_input) + $(AM_V_GEN) $(GROFF) -Tascii $(GROFF_FLAGS) $(spec_input) \ + 2> index.txt.raw > $@ + +widgets.html: $(spec_input) + $(AM_V_GEN) $(GROFF) -Thtml $(GROFF_FLAGS) $(spec_input) \ + 2> index.html.raw > $@ + +index.raw: widgets.ps + +index.pageno: index.raw + $(AM_V_GEN)$(SED) -n '$$p' index.raw > $@ + +index.troff: index.raw + $(AM_V_GEN)$(GREP) '^[1-9]' index.raw | \ + (sort -f '-t:' -k2,2 -k1,1n 2>/dev/null || \ + sort -f '-t:' +1 -3 +0n -1n) | \ + $(AWK) -f $(srcdir)/fixindex.awk | \ + $(AWK) -f $(srcdir)/block.awk > $@ + +widgets.index.ps: widg.idxmac.t index.troff index.pageno + $(AM_V_GEN)$(GROFF) -me $(GROFF_DEFS) \ + $(srcdir)/widg.idxmac.t $(srcdir)/$(XIDXMACROS) index.troff > $@ + + +# Useful for running off part of the manual by hand, +# e.g., make part PART=Label +part: $(srcdir)/$(PART) + $(GROFF) -Tps $(GROFF_FLAGS) $(EVERYWHERE) $(srcdir)/$(PART) > $(PART).ps + +endif BUILD_DOCS diff --git a/libXaw/spec/Makefile.in b/libXaw/spec/Makefile.in new file mode 100644 index 000000000..a57ed02c2 --- /dev/null +++ b/libXaw/spec/Makefile.in @@ -0,0 +1,513 @@ +# Makefile.in generated by automake 1.11 from Makefile.am. +# @configure_input@ + +# Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, +# 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, +# Inc. +# This Makefile.in is free software; the Free Software Foundation +# gives unlimited permission to copy and/or distribute it, +# with or without modifications, as long as this notice is preserved. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY, to the extent permitted by law; without +# even the implied warranty of MERCHANTABILITY or FITNESS FOR A +# PARTICULAR PURPOSE. + +@SET_MAKE@ + +# +# Copyright 2009 Sun Microsystems, Inc. All rights reserved. +# +# Permission to use, copy, modify, distribute, and sell this software and its +# documentation for any purpose is hereby granted without fee, provided that +# the above copyright notice appear in all copies and that both that +# copyright notice and this permission notice appear in supporting +# documentation. +# +# The above copyright notice and this permission notice shall be included +# in all copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +# OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +# IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR +# OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +# ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +# OTHER DEALINGS IN THE SOFTWARE. +# +# Except as contained in this notice, the name of the copyright holders 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 copyright holders. +# + +# Based on xc/doc/specs/Xaw/Makefile from X11R6.9 + +VPATH = @srcdir@ +pkgdatadir = $(datadir)/@PACKAGE@ +pkgincludedir = $(includedir)/@PACKAGE@ +pkglibdir = $(libdir)/@PACKAGE@ +pkglibexecdir = $(libexecdir)/@PACKAGE@ +am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd +install_sh_DATA = $(install_sh) -c -m 644 +install_sh_PROGRAM = $(install_sh) -c +install_sh_SCRIPT = $(install_sh) -c +INSTALL_HEADER = $(INSTALL_DATA) +transform = $(program_transform_name) +NORMAL_INSTALL = : +PRE_INSTALL = : +POST_INSTALL = : +NORMAL_UNINSTALL = : +PRE_UNINSTALL = : +POST_UNINSTALL = : +build_triplet = @build@ +host_triplet = @host@ +subdir = spec +DIST_COMMON = $(srcdir)/Makefile.am $(srcdir)/Makefile.in +ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 +am__aclocal_m4_deps = $(top_srcdir)/configure.ac +am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ + $(ACLOCAL_M4) +mkinstalldirs = $(install_sh) -d +CONFIG_HEADER = $(top_builddir)/config.h +CONFIG_CLEAN_FILES = +CONFIG_CLEAN_VPATH_FILES = +AM_V_GEN = $(am__v_GEN_$(V)) +am__v_GEN_ = $(am__v_GEN_$(AM_DEFAULT_VERBOSITY)) +am__v_GEN_0 = @echo " GEN " $@; +AM_V_at = $(am__v_at_$(V)) +am__v_at_ = $(am__v_at_$(AM_DEFAULT_VERBOSITY)) +am__v_at_0 = @ +SOURCES = +DIST_SOURCES = +am__vpath_adj_setup = srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; +am__vpath_adj = case $$p in \ + $(srcdir)/*) f=`echo "$$p" | sed "s|^$$srcdirstrip/||"`;; \ + *) f=$$p;; \ + esac; +am__strip_dir = f=`echo $$p | sed -e 's|^.*/||'`; +am__install_max = 40 +am__nobase_strip_setup = \ + srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*|]/\\\\&/g'` +am__nobase_strip = \ + for p in $$list; do echo "$$p"; done | sed -e "s|$$srcdirstrip/||" +am__nobase_list = $(am__nobase_strip_setup); \ + for p in $$list; do echo "$$p $$p"; done | \ + sed "s| $$srcdirstrip/| |;"' / .*\//!s/ .*/ ./; s,\( .*\)/[^/]*$$,\1,' | \ + $(AWK) 'BEGIN { files["."] = "" } { files[$$2] = files[$$2] " " $$1; \ + if (++n[$$2] == $(am__install_max)) \ + { print $$2, files[$$2]; n[$$2] = 0; files[$$2] = "" } } \ + END { for (dir in files) print dir, files[dir] }' +am__base_list = \ + sed '$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;s/\n/ /g' | \ + sed '$$!N;$$!N;$$!N;$$!N;s/\n/ /g' +am__installdirs = "$(DESTDIR)$(docdir)" +DATA = $(doc_DATA) +DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) +ACLOCAL = @ACLOCAL@ +ADMIN_MAN_DIR = @ADMIN_MAN_DIR@ +ADMIN_MAN_SUFFIX = @ADMIN_MAN_SUFFIX@ +AMTAR = @AMTAR@ +AM_DEFAULT_VERBOSITY = @AM_DEFAULT_VERBOSITY@ +APP_MAN_DIR = @APP_MAN_DIR@ +APP_MAN_SUFFIX = @APP_MAN_SUFFIX@ +AR = @AR@ +AUTOCONF = @AUTOCONF@ +AUTOHEADER = @AUTOHEADER@ +AUTOMAKE = @AUTOMAKE@ +AWK = @AWK@ +CC = @CC@ +CCDEPMODE = @CCDEPMODE@ +CFLAGS = @CFLAGS@ +CHANGELOG_CMD = @CHANGELOG_CMD@ +CPP = @CPP@ +CPPFLAGS = @CPPFLAGS@ +CWARNFLAGS = @CWARNFLAGS@ +CXX = @CXX@ +CXXCPP = @CXXCPP@ +CXXDEPMODE = @CXXDEPMODE@ +CXXFLAGS = @CXXFLAGS@ +CYGPATH_W = @CYGPATH_W@ +DEFS = @DEFS@ +DEPDIR = @DEPDIR@ +DRIVER_MAN_DIR = @DRIVER_MAN_DIR@ +DRIVER_MAN_SUFFIX = @DRIVER_MAN_SUFFIX@ +DSYMUTIL = @DSYMUTIL@ +ECHO = @ECHO@ +ECHO_C = @ECHO_C@ +ECHO_N = @ECHO_N@ +ECHO_T = @ECHO_T@ +EGREP = @EGREP@ +EXEEXT = @EXEEXT@ +F77 = @F77@ +FFLAGS = @FFLAGS@ +FILE_MAN_DIR = @FILE_MAN_DIR@ +FILE_MAN_SUFFIX = @FILE_MAN_SUFFIX@ +GREP = @GREP@ +GROFF = @GROFF@ +INSTALL = @INSTALL@ +INSTALL_DATA = @INSTALL_DATA@ +INSTALL_PROGRAM = @INSTALL_PROGRAM@ +INSTALL_SCRIPT = @INSTALL_SCRIPT@ +INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@ +LDFLAGS = @LDFLAGS@ +LIBEXT = @LIBEXT@ +LIBOBJS = @LIBOBJS@ +LIBS = @LIBS@ +LIBTOOL = @LIBTOOL@ +LIB_MAN_DIR = @LIB_MAN_DIR@ +LIB_MAN_SUFFIX = @LIB_MAN_SUFFIX@ +LN_S = @LN_S@ +LTLIBOBJS = @LTLIBOBJS@ +MAKEINFO = @MAKEINFO@ +MISC_MAN_DIR = @MISC_MAN_DIR@ +MISC_MAN_SUFFIX = @MISC_MAN_SUFFIX@ +MKDIR_P = @MKDIR_P@ +NMEDIT = @NMEDIT@ +OBJEXT = @OBJEXT@ +PACKAGE = @PACKAGE@ +PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@ +PACKAGE_NAME = @PACKAGE_NAME@ +PACKAGE_STRING = @PACKAGE_STRING@ +PACKAGE_TARNAME = @PACKAGE_TARNAME@ +PACKAGE_VERSION = @PACKAGE_VERSION@ +PATH_SEPARATOR = @PATH_SEPARATOR@ +PKG_CONFIG = @PKG_CONFIG@ +RANLIB = @RANLIB@ +SED = @SED@ +SET_MAKE = @SET_MAKE@ +SHELL = @SHELL@ +STRIP = @STRIP@ +VERSION = @VERSION@ +XAW6_CFLAGS = @XAW6_CFLAGS@ +XAW6_LIBS = @XAW6_LIBS@ +XAW7_CFLAGS = @XAW7_CFLAGS@ +XAW7_LIBS = @XAW7_LIBS@ +abs_builddir = @abs_builddir@ +abs_srcdir = @abs_srcdir@ +abs_top_builddir = @abs_top_builddir@ +abs_top_srcdir = @abs_top_srcdir@ +ac_ct_CC = @ac_ct_CC@ +ac_ct_CXX = @ac_ct_CXX@ +ac_ct_F77 = @ac_ct_F77@ +am__include = @am__include@ +am__leading_dot = @am__leading_dot@ +am__quote = @am__quote@ +am__tar = @am__tar@ +am__untar = @am__untar@ +bindir = @bindir@ +build = @build@ +build_alias = @build_alias@ +build_cpu = @build_cpu@ +build_os = @build_os@ +build_vendor = @build_vendor@ +builddir = @builddir@ +datadir = @datadir@ +datarootdir = @datarootdir@ +distcleancheck_listfiles = @distcleancheck_listfiles@ +docdir = @docdir@ +dvidir = @dvidir@ +exec_prefix = @exec_prefix@ +host = @host@ +host_alias = @host_alias@ +host_cpu = @host_cpu@ +host_os = @host_os@ +host_vendor = @host_vendor@ +htmldir = @htmldir@ +includedir = @includedir@ +infodir = @infodir@ +install_sh = @install_sh@ +libdir = @libdir@ +libexecdir = @libexecdir@ +localedir = @localedir@ +localstatedir = @localstatedir@ +mandir = @mandir@ +mkdir_p = @mkdir_p@ +oldincludedir = @oldincludedir@ +pdfdir = @pdfdir@ +prefix = @prefix@ +program_transform_name = @program_transform_name@ +psdir = @psdir@ +sbindir = @sbindir@ +sharedstatedir = @sharedstatedir@ +srcdir = @srcdir@ +sysconfdir = @sysconfdir@ +target_alias = @target_alias@ +top_build_prefix = @top_build_prefix@ +top_builddir = @top_builddir@ +top_srcdir = @top_srcdir@ +XDOCMACROS = macros.t +XIDXMACROS = indexmacros.t +EVERYWHERE = $(XDOCMACROS) 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 +spec_sources = \ + $(EVERYWHERE) TPage_Credits \ + $(CHAPTER1) $(CHAPTER2) $(CHAPTER3) $(CHAPTER4) \ + $(CHAPTER5) $(CHAPTER6) $(CHAPTER7) + +spec_input = $(spec_sources:%=$(srcdir)/%) +EXTRA_DIST = $(spec_sources) $(XIDXMACROS) block.awk fixindex.awk widg.idxmac.t +@BUILD_DOCS_TRUE@doc_DATA = widgets.ps widgets.index.ps widgets.txt widgets.html +@BUILD_DOCS_TRUE@CLEANFILES = $(doc_DATA) +@BUILD_DOCS_TRUE@MOSTLYCLEANFILES = index.* +@BUILD_DOCS_TRUE@GROFF_DEFS = -dxV="$(PACKAGE_STRING)" +@BUILD_DOCS_TRUE@GROFF_FLAGS = -t -ms $(GROFF_DEFS) +all: all-am + +.SUFFIXES: +$(srcdir)/Makefile.in: $(srcdir)/Makefile.am $(am__configure_deps) + @for dep in $?; do \ + case '$(am__configure_deps)' in \ + *$$dep*) \ + ( cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh ) \ + && { if test -f $@; then exit 0; else break; fi; }; \ + exit 1;; \ + esac; \ + done; \ + echo ' cd $(top_srcdir) && $(AUTOMAKE) --gnu spec/Makefile'; \ + $(am__cd) $(top_srcdir) && \ + $(AUTOMAKE) --gnu spec/Makefile +.PRECIOUS: Makefile +Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status + @case '$?' in \ + *config.status*) \ + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \ + *) \ + echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \ + cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \ + esac; + +$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh + +$(top_srcdir)/configure: $(am__configure_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(ACLOCAL_M4): $(am__aclocal_m4_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(am__aclocal_m4_deps): + +mostlyclean-libtool: + -rm -f *.lo + +clean-libtool: + -rm -rf .libs _libs +install-docDATA: $(doc_DATA) + @$(NORMAL_INSTALL) + test -z "$(docdir)" || $(MKDIR_P) "$(DESTDIR)$(docdir)" + @list='$(doc_DATA)'; test -n "$(docdir)" || list=; \ + for p in $$list; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + echo "$$d$$p"; \ + done | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(docdir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(docdir)" || exit $$?; \ + done + +uninstall-docDATA: + @$(NORMAL_UNINSTALL) + @list='$(doc_DATA)'; test -n "$(docdir)" || list=; \ + files=`for p in $$list; do echo $$p; done | sed -e 's|^.*/||'`; \ + test -n "$$files" || exit 0; \ + echo " ( cd '$(DESTDIR)$(docdir)' && rm -f" $$files ")"; \ + cd "$(DESTDIR)$(docdir)" && rm -f $$files +tags: TAGS +TAGS: + +ctags: CTAGS +CTAGS: + + +distdir: $(DISTFILES) + @srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + list='$(DISTFILES)'; \ + dist_files=`for file in $$list; do echo $$file; done | \ + sed -e "s|^$$srcdirstrip/||;t" \ + -e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \ + case $$dist_files in \ + */*) $(MKDIR_P) `echo "$$dist_files" | \ + sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \ + sort -u` ;; \ + esac; \ + for file in $$dist_files; do \ + if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \ + if test -d $$d/$$file; then \ + dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \ + if test -d "$(distdir)/$$file"; then \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ + fi; \ + if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \ + cp -fpR $(srcdir)/$$file "$(distdir)$$dir" || exit 1; \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ + fi; \ + cp -fpR $$d/$$file "$(distdir)$$dir" || exit 1; \ + else \ + test -f "$(distdir)/$$file" \ + || cp -p $$d/$$file "$(distdir)/$$file" \ + || exit 1; \ + fi; \ + done +check-am: all-am +check: check-am +all-am: Makefile $(DATA) +installdirs: + for dir in "$(DESTDIR)$(docdir)"; do \ + test -z "$$dir" || $(MKDIR_P) "$$dir"; \ + done +install: install-am +install-exec: install-exec-am +install-data: install-data-am +uninstall: uninstall-am + +install-am: all-am + @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am + +installcheck: installcheck-am +install-strip: + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + `test -z '$(STRIP)' || \ + echo "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'"` install +mostlyclean-generic: + -test -z "$(MOSTLYCLEANFILES)" || rm -f $(MOSTLYCLEANFILES) + +clean-generic: + -test -z "$(CLEANFILES)" || rm -f $(CLEANFILES) + +distclean-generic: + -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES) + -test . = "$(srcdir)" || test -z "$(CONFIG_CLEAN_VPATH_FILES)" || rm -f $(CONFIG_CLEAN_VPATH_FILES) + +maintainer-clean-generic: + @echo "This command is intended for maintainers to use" + @echo "it deletes files that may require special tools to rebuild." +clean: clean-am + +clean-am: clean-generic clean-libtool mostlyclean-am + +distclean: distclean-am + -rm -f Makefile +distclean-am: clean-am distclean-generic + +dvi: dvi-am + +dvi-am: + +html: html-am + +html-am: + +info: info-am + +info-am: + +install-data-am: install-docDATA + +install-dvi: install-dvi-am + +install-dvi-am: + +install-exec-am: + +install-html: install-html-am + +install-html-am: + +install-info: install-info-am + +install-info-am: + +install-man: + +install-pdf: install-pdf-am + +install-pdf-am: + +install-ps: install-ps-am + +install-ps-am: + +installcheck-am: + +maintainer-clean: maintainer-clean-am + -rm -f Makefile +maintainer-clean-am: distclean-am maintainer-clean-generic + +mostlyclean: mostlyclean-am + +mostlyclean-am: mostlyclean-generic mostlyclean-libtool + +pdf: pdf-am + +pdf-am: + +ps: ps-am + +ps-am: + +uninstall-am: uninstall-docDATA + +.MAKE: install-am install-strip + +.PHONY: all all-am check check-am clean clean-generic clean-libtool \ + distclean distclean-generic distclean-libtool distdir dvi \ + dvi-am html html-am info info-am install install-am \ + install-data install-data-am install-docDATA install-dvi \ + install-dvi-am install-exec install-exec-am install-html \ + install-html-am install-info install-info-am install-man \ + install-pdf install-pdf-am install-ps install-ps-am \ + install-strip installcheck installcheck-am installdirs \ + maintainer-clean maintainer-clean-generic mostlyclean \ + mostlyclean-generic mostlyclean-libtool pdf pdf-am ps ps-am \ + uninstall uninstall-am uninstall-docDATA + + +@BUILD_DOCS_TRUE@widgets.ps: $(spec_input) +@BUILD_DOCS_TRUE@ -$(AM_V_GEN) $(GROFF) -Tps $(GROFF_FLAGS) $(spec_input) \ +@BUILD_DOCS_TRUE@ 2> index.raw > $@ +@BUILD_DOCS_TRUE@ @if grep '^[^1-9.]' index.raw | grep -v warning; then exit 1; \ +@BUILD_DOCS_TRUE@ else test $$? -le 1; fi + +@BUILD_DOCS_TRUE@widgets.txt: $(spec_input) +@BUILD_DOCS_TRUE@ $(AM_V_GEN) $(GROFF) -Tascii $(GROFF_FLAGS) $(spec_input) \ +@BUILD_DOCS_TRUE@ 2> index.txt.raw > $@ + +@BUILD_DOCS_TRUE@widgets.html: $(spec_input) +@BUILD_DOCS_TRUE@ $(AM_V_GEN) $(GROFF) -Thtml $(GROFF_FLAGS) $(spec_input) \ +@BUILD_DOCS_TRUE@ 2> index.html.raw > $@ + +@BUILD_DOCS_TRUE@index.raw: widgets.ps + +@BUILD_DOCS_TRUE@index.pageno: index.raw +@BUILD_DOCS_TRUE@ $(AM_V_GEN)$(SED) -n '$$p' index.raw > $@ + +@BUILD_DOCS_TRUE@index.troff: index.raw +@BUILD_DOCS_TRUE@ $(AM_V_GEN)$(GREP) '^[1-9]' index.raw | \ +@BUILD_DOCS_TRUE@ (sort -f '-t:' -k2,2 -k1,1n 2>/dev/null || \ +@BUILD_DOCS_TRUE@ sort -f '-t:' +1 -3 +0n -1n) | \ +@BUILD_DOCS_TRUE@ $(AWK) -f $(srcdir)/fixindex.awk | \ +@BUILD_DOCS_TRUE@ $(AWK) -f $(srcdir)/block.awk > $@ + +@BUILD_DOCS_TRUE@widgets.index.ps: widg.idxmac.t index.troff index.pageno +@BUILD_DOCS_TRUE@ $(AM_V_GEN)$(GROFF) -me $(GROFF_DEFS) \ +@BUILD_DOCS_TRUE@ $(srcdir)/widg.idxmac.t $(srcdir)/$(XIDXMACROS) index.troff > $@ + +# Useful for running off part of the manual by hand, +# e.g., make part PART=Label +@BUILD_DOCS_TRUE@part: $(srcdir)/$(PART) +@BUILD_DOCS_TRUE@ $(GROFF) -Tps $(GROFF_FLAGS) $(EVERYWHERE) $(srcdir)/$(PART) > $(PART).ps + +# Tell versions [3.59,3.63) of GNU make to not export all variables. +# Otherwise a system limit (for SysV at least) may be exceeded. +.NOEXPORT: diff --git a/libXaw/spec/MenuButton b/libXaw/spec/MenuButton new file mode 100644 index 000000000..8a4084b1c --- /dev/null +++ b/libXaw/spec/MenuButton @@ -0,0 +1,215 @@ +.\" $Xorg: MenuButton,v 1.3 2000/08/17 19:42:27 cpqbld 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/libXaw/spec/Paned b/libXaw/spec/Paned new file mode 100644 index 000000000..a6b8f0089 --- /dev/null +++ b/libXaw/spec/Paned @@ -0,0 +1,492 @@ +.\" $Xorg: Paned,v 1.3 2000/08/17 19:42:27 cpqbld 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/libXaw/spec/Panner b/libXaw/spec/Panner new file mode 100644 index 000000000..1bb11b5fd --- /dev/null +++ b/libXaw/spec/Panner @@ -0,0 +1,247 @@ +.\" $Xorg: Panner,v 1.3 2000/08/17 19:42:27 cpqbld 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/libXaw/spec/Porthole b/libXaw/spec/Porthole new file mode 100644 index 000000000..4d4104aa0 --- /dev/null +++ b/libXaw/spec/Porthole @@ -0,0 +1,125 @@ +.\" $Xorg: Porthole,v 1.3 2000/08/17 19:42:27 cpqbld 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/libXaw/spec/Repeater b/libXaw/spec/Repeater new file mode 100644 index 000000000..93872939c --- /dev/null +++ b/libXaw/spec/Repeater @@ -0,0 +1,184 @@ +.\" $Xorg: Repeater,v 1.3 2000/08/17 19:42:27 cpqbld 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/libXaw/spec/Scrollbar b/libXaw/spec/Scrollbar new file mode 100644 index 000000000..faf693a3b --- /dev/null +++ b/libXaw/spec/Scrollbar @@ -0,0 +1,386 @@ +.\" $Xorg: Scrollbar,v 1.3 2000/08/17 19:42:27 cpqbld 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/libXaw/spec/Simple b/libXaw/spec/Simple new file mode 100644 index 000000000..a030d4012 --- /dev/null +++ b/libXaw/spec/Simple @@ -0,0 +1,95 @@ +.\" $Xorg: Simple,v 1.3 2000/08/17 19:42:27 cpqbld 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/libXaw/spec/SimpleMenu b/libXaw/spec/SimpleMenu new file mode 100644 index 000000000..b59e511c8 --- /dev/null +++ b/libXaw/spec/SimpleMenu @@ -0,0 +1,315 @@ +.\" $Xorg: SimpleMenu,v 1.3 2000/08/17 19:42:27 cpqbld 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/libXaw/spec/Sme b/libXaw/spec/Sme new file mode 100644 index 000000000..48eaa1510 --- /dev/null +++ b/libXaw/spec/Sme @@ -0,0 +1,106 @@ +.\" $Xorg: Sme,v 1.3 2000/08/17 19:42:28 cpqbld 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/libXaw/spec/SmeBSB b/libXaw/spec/SmeBSB new file mode 100644 index 000000000..2cfae9d8f --- /dev/null +++ b/libXaw/spec/SmeBSB @@ -0,0 +1,125 @@ +.\" $Xorg: SmeBSB,v 1.3 2000/08/17 19:42:28 cpqbld 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/libXaw/spec/SmeLine b/libXaw/spec/SmeLine new file mode 100644 index 000000000..5b87cd9a5 --- /dev/null +++ b/libXaw/spec/SmeLine @@ -0,0 +1,72 @@ +.\" $Xorg: SmeLine,v 1.3 2000/08/17 19:42:28 cpqbld 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/libXaw/spec/StripChart b/libXaw/spec/StripChart new file mode 100644 index 000000000..3a4e68338 --- /dev/null +++ b/libXaw/spec/StripChart @@ -0,0 +1,160 @@ +.\" $Xorg: StripChart,v 1.3 2000/08/17 19:42:28 cpqbld 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/libXaw/spec/TPage_Credits b/libXaw/spec/TPage_Credits new file mode 100644 index 000000000..7301ddf63 --- /dev/null +++ b/libXaw/spec/TPage_Credits @@ -0,0 +1,156 @@ +.\" $Xorg: TPage_Credits,v 1.3 2000/08/17 19:42:28 cpqbld Exp $ +.\" $XdotOrg: xc/doc/specs/Xaw/TPage_Credits,v 1.2 2004/04/23 18:42:18 eich Exp $ +.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 7\fP\s-1 + +\s+1\fB\*(xV\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 The Open Group. +.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/libXaw/spec/Template b/libXaw/spec/Template new file mode 100644 index 000000000..b5dc050b2 --- /dev/null +++ b/libXaw/spec/Template @@ -0,0 +1,426 @@ +.\" $Xorg: Template,v 1.3 2000/08/17 19:42:28 cpqbld 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/libXaw/spec/Text b/libXaw/spec/Text new file mode 100644 index 000000000..7fea09a19 --- /dev/null +++ b/libXaw/spec/Text @@ -0,0 +1,123 @@ +.\" $Xorg: Text,v 1.3 2000/08/17 19:42:28 cpqbld 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 a 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/libXaw/spec/TextActions b/libXaw/spec/TextActions new file mode 100644 index 000000000..69c89c9ac --- /dev/null +++ b/libXaw/spec/TextActions @@ -0,0 +1,506 @@ +.\" $Xorg: TextActions,v 1.3 2000/08/17 19:42:28 cpqbld 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/libXaw/spec/TextCustom b/libXaw/spec/TextCustom new file mode 100644 index 000000000..fbb656970 --- /dev/null +++ b/libXaw/spec/TextCustom @@ -0,0 +1,63 @@ +.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/libXaw/spec/TextFuncs b/libXaw/spec/TextFuncs new file mode 100644 index 000000000..ea26068a5 --- /dev/null +++ b/libXaw/spec/TextFuncs @@ -0,0 +1,397 @@ +.\" $Xorg: TextFuncs,v 1.3 2000/08/17 19:42:28 cpqbld 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/libXaw/spec/TextSink b/libXaw/spec/TextSink new file mode 100644 index 000000000..72ae3cf99 --- /dev/null +++ b/libXaw/spec/TextSink @@ -0,0 +1,420 @@ +.\" $Xorg: TextSink,v 1.3 2000/08/17 19:42:28 cpqbld 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/libXaw/spec/TextSource b/libXaw/spec/TextSource new file mode 100644 index 000000000..852db2dd3 --- /dev/null +++ b/libXaw/spec/TextSource @@ -0,0 +1,331 @@ +.\" $Xorg: TextSource,v 1.3 2000/08/17 19:42:28 cpqbld 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 text position immediately after the +characters read from the +text buffer. The function is not required to read \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/libXaw/spec/Toggle b/libXaw/spec/Toggle new file mode 100644 index 000000000..12a605bd2 --- /dev/null +++ b/libXaw/spec/Toggle @@ -0,0 +1,370 @@ +.\" $Xorg: Toggle,v 1.3 2000/08/17 19:42:29 cpqbld 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 widgets 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/libXaw/spec/Tree b/libXaw/spec/Tree new file mode 100644 index 000000000..5575228fb --- /dev/null +++ b/libXaw/spec/Tree @@ -0,0 +1,181 @@ +.\" $Xorg: Tree,v 1.3 2000/08/17 19:42:29 cpqbld 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/libXaw/spec/Viewport b/libXaw/spec/Viewport new file mode 100644 index 000000000..0b599472a --- /dev/null +++ b/libXaw/spec/Viewport @@ -0,0 +1,156 @@ +.\" $Xorg: Viewport,v 1.3 2000/08/17 19:42:29 cpqbld 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/libXaw/spec/block.awk b/libXaw/spec/block.awk new file mode 100644 index 000000000..0dd75f3f7 --- /dev/null +++ b/libXaw/spec/block.awk @@ -0,0 +1,22 @@ +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/libXaw/spec/fixindex.awk b/libXaw/spec/fixindex.awk new file mode 100644 index 000000000..e8849f3bd --- /dev/null +++ b/libXaw/spec/fixindex.awk @@ -0,0 +1,73 @@ +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/libXaw/spec/indexmacros.t b/libXaw/spec/indexmacros.t new file mode 100644 index 000000000..4660f18ed --- /dev/null +++ b/libXaw/spec/indexmacros.t @@ -0,0 +1,42 @@ +. \" Macros for the index +.de Ib \" blank major entry +.br +.ne 2v +\\$1: +.. +.de I> \" major entry +.br +\\$1, \\$2 +.. +.de I< \" minor entry +.br + \\$2, \\$3 +.. +.de LB \" new letter starts here +.di DT \" start diverted text +.sp +.sz +2 +.b +\\$1 +.r +.sz -2 +.sp +.di \" end diverted text +.ne \\n(dnu+1v \" get enough space for it +.DT \" output it +.. +.\" set up various parameters for the right evironment. +.\" Your taste may be different. +.ef ''\fB % \fP'' +.of ''\fB % \fP'' +.++ A +.po 1.0i \" physical offset +.ta 5iR \" right alignment tab +.lp \" initialize -me +.ce +.sz 18 +Index +.sp 1 +.sz 10 +.2c \" 2 column mode +.sp 3 diff --git a/libXaw/spec/macros.t b/libXaw/spec/macros.t new file mode 100644 index 000000000..cbc599b3f --- /dev/null +++ b/libXaw/spec/macros.t @@ -0,0 +1,226 @@ +.\" $Xorg: macros.t,v 1.3 2000/08/17 19:42:51 cpqbld Exp $ +.\" macros.t -- macros for X Consortium documents +.\" Revised and commented by smarks 93.12.20. +.\" +.\" global setup: set ragged right, assign string variables +.\" +.na +.ie n \{\ +.ds Q \&" +.ds U \&" +.ds - \%-- +.\} +.el \{\ +.ds Q `\h'-\w'\^'u'` +.ds U '\h'-\w'\^'u'' +.ds - \(em +.\} +.\" +.\" --- Ds --- displayed text (like .DS) with no keep +.\" .Ds is obsolete. Change to something from this table: +.\" for this use instead +.\" .Ds .ID +.\" .Ds n .LD (where "n" is a number) +.\" (Numbers don't work in these macros, so ".Ds 5" +.\" comes out the same as ".Ds 0".) +.\" +.de Ds +.nf +.\\$1D \\$2 \\$1 +.ft 1 +.ps \\n(PS +.if \\n(VS>=40 .vs \\n(VSu +.if \\n(VS<=39 .vs \\n(VSp +.. +.de D +.ID \\$1 +.. +.de 0D +.LD +.. +.\" backward compatibility for the Xt spec +.de 5D +.LD +.. +.\" +.\" --- De --- obsolete: use .DE instead +.\" +.de De +.DE +.. +.\" +.\" --- FD --- +.\" +.de FD +.LP +.KS +.TA .5i 3i +.ta .5i 3i +.nf +.. +.\" +.\" --- FN --- +.\" +.de FN +.fi +.KE +.LP +.. +.\" +.\" --- IN --- send an index entry to the stderr +.\" +.de IN +.tm \\n%:\\$1:\\$2:\\$3 +.. +.\" +.\" --- C{ --- +.\" +.de C{ +.KS +.nf +.D +.\" +.\" choose appropriate monospace font +.\" the imagen conditional, 480, +.\" may be changed to L if LB is too +.\" heavy for your eyes... +.\" +.ie "\\*(.T"480" .ft L +.el .ie "\\*(.T"300" .ft L +.el .ie "\\*(.T"202" .ft PO +.el .ie "\\*(.T"aps" .ft CW +.el .ft R +.ps \\n(PS +.ie \\n(VS>40 .vs \\n(VSu +.el .vs \\n(VSp +.. +.\" +.\" --- C} --- +.\" +.de C} +.DE +.R +.. +.\" +.\" --- Pn --- like PN, but use $2; $1 and $3 abut +.\" +.de Pn +.IN \\$2 +.ie t \\$1\fB\^\\$2\^\fR\\$3 +.el \\$1\fI\^\\$2\^\fP\\$3 +.. +.\" +.\" --- PN --- put $1 in boldface and add index entry; $2 abuts +.\" +.de PN +.IN \\$1 +.ie t \fB\^\\$1\^\fR\\$2 +.el \fI\^\\$1\^\fP\\$2 +.. +.\" +.\" --- hI --- add index entry for $1 as header file +.\" +.de hI +.IN <\\$1> +.IN Files <\\$1> +.IN Headers <\\$1> +.. +.\" +.\" --- hN --- put $1 in boldface as header and add index entry; $2 abuts +.\" +.de hN +.hI \\$1 +.ie t <\fB\\$1\fR>\\$2 +.el <\fI\\$1\fP>\\$2 +.. +.\" +.\" --- NT --- +.\" +.de NT +.br +.ne 7 +.ds NO Note +.if \\n(.$ .ds NO \\$1 +.ie n .sp +.el .sp 10p +.ce +\\*(NO +.ie n .sp +.el .sp 5p +.if '\\$1'C' .ce 99 +.if '\\$2'C' .ce 99 +.\" .QS/.QE macros don't exist in older versions of -ms +.ie \\n(GS .QS +.el \{\ +. in +5n +. ll -5n +.\} +.R +.. +.\" +.\" --- NE --- Note End (doug kraft 3/85) +.\" +.de NE +.ce 0 +.ie \\n(GS .QE +.el \{\ +. in -5n +. ll +5n +.\} +.ie n .sp +.el .sp 10p +.. +.\" +.\" --- nH --- numbered header (like NH) but with automatic TOC entry +.\" usage: .nH level "section title, preferable in quotes" +.\" +.de nH +.NH \\$1 +\\$2 +.XS +\\*(SN \\$2 +.XE +.. +.\" +.\" --- sM --- put start-marker in margin +.\" +.de sM +.KS +.sp 1 +\\h'-0.5i'\\L'-1v'\\v'1p'\\l'1v'\\v'1v-1p' +.sp -1 +.. +.\" +.\" --- eM --- put end-marker in margin +.\" +.de eM +.sp -1 +\\h'-0.5i'\\L'-1v'\\v'1v+1p'\\l'1v'\\v'-1p' +.sp 1 +.KE +.. +.\" +.\" --- YZ --- finish up; $1 is the starting page number of the TOC +.\" +.de YZ +. \" Force there to be an even number of pages, so the table of +. \" contents doesn't end up on the back of the last page in +. \" the case of duplex printing. +.if o .bp +. \" Emit a .pn directive with one plus the last page number. + \" This will be the number of the first page of the index. +.nr YZ \\n%+1 +.tm .pn \\n(YZ +. \" Issue the table of contents, setting roman numerals, +. \" and redefining the footer to use them. +.bp \\$1 +.af PN i +.EF ''\\\\\\\\n(PN'' +.OF ''\\\\\\\\n(PN'' +. \" Why all the backslashes? This string is evaluated +. \" three times: 1) during the definition of this macro, +. \" 2) when the .EF and .OF macros are expanded, and 3) +. \" when the bottom-of-page trap is invoked. Thus, +. \" eight backslashes are reduced to one in the final output. +.PX +.. diff --git a/libXaw/spec/strings.mit b/libXaw/spec/strings.mit new file mode 100644 index 000000000..e8a339bf2 --- /dev/null +++ b/libXaw/spec/strings.mit @@ -0,0 +1,10 @@ +.\" $Xorg: strings.mit,v 1.3 2000/08/17 19:42:29 cpqbld 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/libXaw/spec/strings.xaw b/libXaw/spec/strings.xaw new file mode 100644 index 000000000..7ef362ef8 --- /dev/null +++ b/libXaw/spec/strings.xaw @@ -0,0 +1,714 @@ +.\" $Xorg: strings.xaw,v 1.3 2000/08/17 19:42:29 cpqbld 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. +Regardless 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 \fBXawAsciiSourceFreeString\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/libXaw/spec/widg.idxmac.t b/libXaw/spec/widg.idxmac.t new file mode 100644 index 000000000..b464a1a7d --- /dev/null +++ b/libXaw/spec/widg.idxmac.t @@ -0,0 +1,3 @@ +.eh '\fBAthena Widget Set\fP''\fB\*(xV\fP' +.oh '\fBAthena Widget Set\fP''\fB\*(xV\fP' +.so index.pageno |