'\" t
...\" ResolveP.sgm /main/9 1996/09/25 10:05:19 cdedoc $
.de P!
.fl
\!!1 setgray
.fl
\\&.\"
.fl
\!!0 setgray
.fl			\" force out current output buffer
\!!save /psv exch def currentpoint translate 0 0 moveto
\!!/showpage{}def
.fl			\" prolog
.sy sed -e 's/^/!/' \\$1\" bring in postscript file
\!!psv restore
.
.de pF
.ie     \\*(f1 .ds f1 \\n(.f
.el .ie \\*(f2 .ds f2 \\n(.f
.el .ie \\*(f3 .ds f3 \\n(.f
.el .ie \\*(f4 .ds f4 \\n(.f
.el .tm ? font overflow
.ft \\$1
..
.de fP
.ie     !\\*(f4 \{\
.	ft \\*(f4
.	ds f4\"
'	br \}
.el .ie !\\*(f3 \{\
.	ft \\*(f3
.	ds f3\"
'	br \}
.el .ie !\\*(f2 \{\
.	ft \\*(f2
.	ds f2\"
'	br \}
.el .ie !\\*(f1 \{\
.	ft \\*(f1
.	ds f1\"
'	br \}
.el .tm ? font underflow
..
.ds f1\"
.ds f2\"
.ds f3\"
.ds f4\"
.ta 8n 16n 24n 32n 40n 48n 56n 64n 72n 
.TH "XmResolvePartOffsets" "library call"
.SH "NAME"
\fBXmResolvePartOffsets\fP \(em A function that allows writing of upward-compatible applications and widgets
.iX "XmResolvePartOffsets"
.SH "SYNOPSIS"
.PP
.nf
#include <Xm/Xm\&.h>
\fBvoid \fBXmResolvePartOffsets\fP\fR(
\fBWidgetClass \fBwidget_class\fR\fR,
\fBXmOffsetPtr \fB* offset\fR\fR);
.fi
.SH "DESCRIPTION"
.PP
The use of offset records requires one extra global variable per widget
class\&.
The variable consists of a pointer to an array of offsets into the
widget record for each part of the widget structure\&.
The \fBXmResolvePartOffsets\fP function
allocates the offset records needed by an application to guarantee
upward-compatible access to widget instance records by
applications and widgets\&.
These offset records are used by the widget to access all of the
widget\&'s variables\&.
A widget needs to take the steps described in the following paragraphs\&.
.PP
Instead of creating a resource list, the widget creates an offset
resource list\&.
To accomplish this, use the \fBXmPartResource\fR
structure and the \fBXmPartOffset\fP macro\&.
The \fBXmPartResource\fR data structure looks just like a
resource list, but instead of having
one integer for its offset, it has two shorts\&.
This structure is put into the class record as if it were a normal resource
list\&. Instead of using \fBXtOffset\fP for the offset, the widget uses
\fBXmPartOffset\fP\&.
.PP
.nf
\f(CWXmPartResource resources[] = {
  { BarNxyz, BarCXyz, XmRBoolean,
    sizeof(Boolean), XmPartOffset(Bar,xyz),
    XmRImmediate, (XtPointer)False }
};\fR
.fi
.PP
.PP
Instead of putting the widget size in the class record, the widget puts the
widget part size in the same field\&.
.PP
Instead of putting \fBXtVersion\fP in the class record, the widget puts
\fBXtVersionDontCheck\fP in the class record\&.
.PP
The widget defines a variable, of type \fBXmOffsetPtr\fR, to point to
the offset record\&.
This can be part of the widget\&'s class record or a separate global
variable\&.
.PP
In class initialization, the widget calls \fBXmResolvePartOffsets\fP,
passing it a pointer to contain the address of the offset
record and the class record\&.
This does several things:
.IP "   \(bu" 6
Adds the superclass (which, by definition, has already been initialized)
size field to the part size field
.IP "   \(bu" 6
Allocates an array based upon the number of superclasses
.IP "   \(bu" 6
Fills in the offsets of all the widget parts with the appropriate
values, determined by examining the size fields of all superclass
records
.IP "   \(bu" 6
Uses the part offset array to modify the offset entries in the resource
list to be real offsets, in place
.PP
The widget defines a constant that will be the index to its part
structure in the offsets array\&.
The value should be 1 greater than
the index of the widget\&'s superclass\&.
Constants defined for all \fBXm\fP
widgets can be found in \fBXmP\&.h\fP\&.
.PP
.nf
\f(CW#define BarIndex (XmBulletinBIndex + 1)\fR
.fi
.PP
.PP
Instead of accessing fields directly, the widget must always go through
the offset table\&.
The \fBXmField\fP macro helps you access these fields\&.
Because the \fBXmPartOffset\fP and \fBXmField\fP
macros concatenate things together, you must
ensure that there is no space
after the part argument\&.
For example, the following macros do not work because of the space
after the part (Label) argument:
.PP
.nf
\f(CWXmField(w, offset, Label, text, char *)
XmPartOffset(Label, text)\fR
.fi
.PP
.PP
Therefore, you must not have any spaces after the part (Label)
argument, as illustrated here:
.PP
.nf
\f(CWXmField(w, offset, Label, text, char *)\fR
.fi
.PP
.PP
You can define macros for each field to make this easier\&.
Assume an integer field \fIxyz\fP:
.PP
.nf
\f(CW#define BarXyz(w) (*(int *)(((char *) w) + \e
        offset[BarIndex] + XtOffset(BarPart,xyz)))\fR
.fi
.PP
.PP
The parameters for \fBXmResolvePartOffsets\fP are
.IP "\fIwidget_class\fP" 10
Specifies the widget class pointer for the created widget
.IP "\fIoffset\fP" 10
Returns the offset record
.SH "RELATED INFORMATION"
.PP
\fBXmResolveAllPartOffsets\fP(3)\&.
...\" created by instant / docbook-to-man, Sun 22 Dec 1996, 20:29