1184 lines
30 KiB
Plaintext
1184 lines
30 KiB
Plaintext
.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
|
|
.\"
|
|
.\" Permission is hereby granted, free of charge, to any person obtaining
|
|
.\" a copy of this software and associated documentation files (the
|
|
.\" "Software"), to deal in the Software without restriction, including
|
|
.\" without limitation the rights to use, copy, modify, merge, publish,
|
|
.\" distribute, sublicense, and/or sell copies of the Software, and to
|
|
.\" permit persons to whom the Software is furnished to do so, subject to
|
|
.\" the following conditions:
|
|
.\"
|
|
.\" The above copyright notice and this permission notice shall be included
|
|
.\" in all copies or substantial portions of the Software.
|
|
.\"
|
|
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
|
|
.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
|
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
|
.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
|
|
.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
|
|
.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
|
|
.\" OTHER DEALINGS IN THE SOFTWARE.
|
|
.\"
|
|
.\" Except as contained in this notice, the name of the X Consortium shall
|
|
.\" not be used in advertising or otherwise to promote the sale, use or
|
|
.\" other dealings in this Software without prior written authorization
|
|
.\" from the X Consortium.
|
|
.\"
|
|
.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
|
|
.\" Digital Equipment Corporation
|
|
.\"
|
|
.\" Portions Copyright \(co 1990, 1991 by
|
|
.\" Tektronix, Inc.
|
|
.\"
|
|
.\" 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 all copies, and that the names of
|
|
.\" Digital and Tektronix not be used in in advertising or publicity pertaining
|
|
.\" to this documentation without specific, written prior permission.
|
|
.\" Digital and Tektronix makes no representations about the suitability
|
|
.\" of this documentation for any purpose.
|
|
.\" It is provided ``as is'' without express or implied warranty.
|
|
.\"
|
|
\&
|
|
.sp 1
|
|
.ce 3
|
|
\s+1\fBAppendix D\fP\s-1
|
|
|
|
\s+1\fBCompatibility Functions\fP\s-1
|
|
.sp 2
|
|
.na
|
|
.LP
|
|
.XS
|
|
Appendix D: Compatibility Functions
|
|
.XE
|
|
.LP
|
|
The X Version 11 and X Version 10 functions discussed in this appendix
|
|
are obsolete, have been superseded by newer X Version 11 functions,
|
|
and are maintained for compatibility reasons only.
|
|
.SH
|
|
X Version 11 Compatibility Functions
|
|
.LP
|
|
You can use the X Version 11 compatibility functions to:
|
|
.IP \(bu 5
|
|
Set standard properties
|
|
.IP \(bu 5
|
|
Set and get window sizing hints
|
|
.IP \(bu 5
|
|
Set and get an
|
|
.PN XStandardColormap
|
|
structure
|
|
.IP \(bu 5
|
|
Parse window geometry
|
|
.IP \(bu 5
|
|
Get X environment defaults
|
|
.SH
|
|
Setting Standard Properties
|
|
.LP
|
|
To specify a minimum set of properties describing the simplest application,
|
|
use
|
|
.PN XSetStandardProperties .
|
|
This function has been superseded by
|
|
.PN XSetWMProperties
|
|
and sets all or portions of the
|
|
WM_NAME, WM_ICON_NAME, WM_HINTS, WM_COMMAND,
|
|
and WM_NORMAL_HINTS properties.
|
|
.IN "XSetStandardProperties" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
XSetStandardProperties\^(\^\fIdisplay\fP, \fIw\fP, \fIwindow_name\fP, \fIicon_name\fP, \fIicon_pixmap\fP, \fIargv\fP, \fIargc\fP, \fIhints\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
Window \fIw\fP\^;
|
|
.br
|
|
char *\fIwindow_name\fP\^;
|
|
.br
|
|
char *\fIicon_name\fP\^;
|
|
.br
|
|
Pixmap \fIicon_pixmap\fP\^;
|
|
.br
|
|
char **\fIargv\fP\^;
|
|
.br
|
|
int \fIargc\fP\^;
|
|
.br
|
|
XSizeHints *\fIhints\fP\^;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.IP \fIw\fP 1i
|
|
Specifies the window.
|
|
.IP \fIwindow_name\fP 1i
|
|
Specifies the window name,
|
|
which should be a null-terminated string.
|
|
.IP \fIicon_name\fP 1i
|
|
Specifies the icon name,
|
|
which should be a null-terminated string.
|
|
.IP \fIicon_pixmap\fP 1i
|
|
Specifies the bitmap that is to be used for the icon or
|
|
.PN None .
|
|
.IP \fIargv\fP 1i
|
|
Specifies the application's argument list.
|
|
.IP \fIargc\fP 1i
|
|
Specifies the number of arguments.
|
|
.IP \fIhints\fP 1i
|
|
Specifies a pointer to the size hints for the window in its normal state.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XSetStandardProperties
|
|
function provides a means by which simple applications set the
|
|
most essential properties with a single call.
|
|
.PN XSetStandardProperties
|
|
should be used to give a window manager some information about
|
|
your program's preferences.
|
|
It should not be used by applications that need
|
|
to communicate more information than is possible with
|
|
.PN XSetStandardProperties .
|
|
(Typically, argv is the argv array of your main program.)
|
|
If the strings are not in the Host Portable Character Encoding,
|
|
the result is implementation-dependent.
|
|
.LP
|
|
.PN XSetStandardProperties
|
|
can generate
|
|
.PN BadAlloc
|
|
and
|
|
.PN BadWindow
|
|
errors.
|
|
.SH
|
|
Setting and Getting Window Sizing Hints
|
|
.LP
|
|
Xlib provides functions that you can use to set or get window sizing hints.
|
|
The functions discussed in this section use the flags and the
|
|
.PN XSizeHints
|
|
structure, as defined in the
|
|
.hN X11/Xutil.h
|
|
header file and use the WM_NORMAL_HINTS property.
|
|
.LP
|
|
.sp
|
|
To set the size hints for a given window in its normal state, use
|
|
.PN XSetNormalHints .
|
|
This function has been superseded by
|
|
.PN XSetWMNormalHints .
|
|
.IN "XSetNormalHints" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
XSetNormalHints\^(\^\fIdisplay\fP, \fIw\fP, \fIhints\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
Window \fIw\fP\^;
|
|
.br
|
|
XSizeHints *\fIhints\fP\^;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.IP \fIw\fP 1i
|
|
Specifies the window.
|
|
.IP \fIhints\fP 1i
|
|
Specifies a pointer to the size hints for the window in its normal state.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XSetNormalHints
|
|
function sets the size hints structure for the specified window.
|
|
Applications use
|
|
.PN XSetNormalHints
|
|
to inform the window manager of the size
|
|
or position desirable for that window.
|
|
In addition,
|
|
an application that wants to move or resize itself should call
|
|
.PN XSetNormalHints
|
|
and specify its new desired location and size
|
|
as well as making direct Xlib calls to move or resize.
|
|
This is because window managers may ignore redirected
|
|
configure requests, but they pay attention to property changes.
|
|
.LP
|
|
To set size hints,
|
|
an application not only must assign values to the appropriate members
|
|
in the hints structure but also must set the flags member of the structure
|
|
to indicate which information is present and where it came from.
|
|
A call to
|
|
.PN XSetNormalHints
|
|
is meaningless, unless the flags member is set to indicate which members of
|
|
the structure have been assigned values.
|
|
.LP
|
|
.PN XSetNormalHints
|
|
can generate
|
|
.PN BadAlloc
|
|
and
|
|
.PN BadWindow
|
|
errors.
|
|
.LP
|
|
.sp
|
|
To return the size hints for a window in its normal state, use
|
|
.PN XGetNormalHints .
|
|
This function has been superseded by
|
|
.PN XGetWMNormalHints .
|
|
.IN "XGetNormalHints" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
Status XGetNormalHints\^(\^\fIdisplay\fP, \fIw\fP, \fIhints_return\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
Window \fIw\fP\^;
|
|
.br
|
|
XSizeHints *\fIhints_return\fP\^;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.IP \fIw\fP 1i
|
|
Specifies the window.
|
|
.IP \fIhints_return\fP 1i
|
|
Returns the size hints for the window in its normal state.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XGetNormalHints
|
|
function returns the size hints for a window in its normal state.
|
|
It returns a nonzero status if it succeeds or zero if
|
|
the application specified no normal size hints for this window.
|
|
.LP
|
|
.PN XGetNormalHints
|
|
can generate a
|
|
.PN BadWindow
|
|
error.
|
|
.LP
|
|
.sp
|
|
The next two functions set and read the WM_ZOOM_HINTS property.
|
|
.LP
|
|
To set the zoom hints for a window, use
|
|
.PN XSetZoomHints .
|
|
This function is no longer supported by the
|
|
\fIInter-Client Communication Conventions Manual\fP.
|
|
.IN "XSetZoomHints" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
XSetZoomHints\^(\^\fIdisplay\fP, \fIw\fP, \fIzhints\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
Window \fIw\fP\^;
|
|
.br
|
|
XSizeHints *\fIzhints\fP\^;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.IP \fIw\fP 1i
|
|
Specifies the window.
|
|
.IP \fIzhints\fP 1i
|
|
Specifies a pointer to the zoom hints.
|
|
.LP
|
|
.eM
|
|
Many window managers think of windows in one of three states:
|
|
iconic, normal, or zoomed.
|
|
The
|
|
.PN XSetZoomHints
|
|
function provides the window manager with information for the window in the
|
|
zoomed state.
|
|
.LP
|
|
.PN XSetZoomHints
|
|
can generate
|
|
.PN BadAlloc
|
|
and
|
|
.PN BadWindow
|
|
errors.
|
|
.LP
|
|
.sp
|
|
To read the zoom hints for a window, use
|
|
.PN XGetZoomHints .
|
|
This function is no longer supported by the
|
|
\fIInter-Client Communication Conventions Manual\fP.
|
|
.IN "XGetZoomHints" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
Status XGetZoomHints\^(\^\fIdisplay\fP, \fIw\fP, \fIzhints_return\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
Window \fIw\fP\^;
|
|
.br
|
|
XSizeHints *\fIzhints_return\fP\^;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.IP \fIw\fP 1i
|
|
Specifies the window.
|
|
.IP \fIzhints_return\fP 1i
|
|
Returns the zoom hints.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XGetZoomHints
|
|
function returns the size hints for a window in its zoomed state.
|
|
It returns a nonzero status if it succeeds or zero if
|
|
the application specified no zoom size hints for this window.
|
|
.LP
|
|
.PN XGetZoomHints
|
|
can generate a
|
|
.PN BadWindow
|
|
error.
|
|
.LP
|
|
.sp
|
|
To set the value of any property of type WM_SIZE_HINTS, use
|
|
.PN XSetSizeHints .
|
|
This function has been superseded by
|
|
.PN XSetWMSizeHints .
|
|
.IN "XSetSizeHints" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
XSetSizeHints\^(\^\fIdisplay\fP, \fIw\fP, \fIhints\fP, \fIproperty\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
Window \fIw\fP\^;
|
|
.br
|
|
XSizeHints *\fIhints\fP\^;
|
|
.br
|
|
Atom \fIproperty\fP\^;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.IP \fIw\fP 1i
|
|
Specifies the window.
|
|
.IP \fIhints\fP 1i
|
|
Specifies a pointer to the size hints.
|
|
.IP \fIproperty\fP 1i
|
|
Specifies the property name.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XSetSizeHints
|
|
function sets the
|
|
.PN XSizeHints
|
|
structure for the named property and the specified window.
|
|
This is used by
|
|
.PN XSetNormalHints
|
|
and
|
|
.PN XSetZoomHints
|
|
and can be used to set the value of any property of type WM_SIZE_HINTS.
|
|
Thus, it may be useful if other properties of that type get defined.
|
|
.LP
|
|
.PN XSetSizeHints
|
|
can generate
|
|
.PN BadAlloc ,
|
|
.PN BadAtom ,
|
|
and
|
|
.PN BadWindow
|
|
errors.
|
|
.LP
|
|
.sp
|
|
To read the value of any property of type WM_SIZE_HINTS, use
|
|
.PN XGetSizeHints .
|
|
This function has been superseded by
|
|
.PN XGetWMSizeHints .
|
|
.IN "XGetSizeHints" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
Status XGetSizeHints\^(\^\fIdisplay\fP, \fIw\fP, \fIhints_return\fP, \fIproperty\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
Window \fIw\fP\^;
|
|
.br
|
|
XSizeHints *\fIhints_return\fP\^;
|
|
.br
|
|
Atom \fIproperty\fP\^;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.IP \fIw\fP 1i
|
|
Specifies the window.
|
|
.IP \fIhints_return\fP 1i
|
|
Returns the size hints.
|
|
.IP \fIproperty\fP 1i
|
|
Specifies the property name.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XGetSizeHints
|
|
function returns the
|
|
.PN XSizeHints
|
|
structure for the named property and the specified window.
|
|
This is used by
|
|
.PN XGetNormalHints
|
|
and
|
|
.PN XGetZoomHints .
|
|
It also can be used to retrieve the value of any property of type
|
|
WM_SIZE_HINTS.
|
|
Thus, it may be useful if other properties of that type get defined.
|
|
.PN XGetSizeHints
|
|
returns a nonzero status if a size hint was defined
|
|
or zero otherwise.
|
|
.LP
|
|
.PN XGetSizeHints
|
|
can generate
|
|
.PN BadAtom
|
|
and
|
|
.PN BadWindow
|
|
errors.
|
|
.SH
|
|
Getting and Setting an XStandardColormap Structure
|
|
.LP
|
|
To get the
|
|
.PN XStandardColormap
|
|
structure associated with one of the described atoms, use
|
|
.PN XGetStandardColormap .
|
|
This function has been superseded by
|
|
.PN XGetRGBColormap .
|
|
.IN "XGetStandardColormap" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
Status XGetStandardColormap(\^\fIdisplay\fP, \fIw\fP, \fIcolormap_return\fP, \fIproperty\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
Window \fIw\fP\^;
|
|
.br
|
|
XStandardColormap *\fIcolormap_return\fP\^;
|
|
.br
|
|
Atom \fIproperty\fP\^; /* RGB_BEST_MAP, etc. */
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.IP \fIw\fP 1i
|
|
Specifies the window.
|
|
.IP \fIcolormap_return\fP 1i
|
|
Returns the colormap associated with the specified atom.
|
|
.IP \fIproperty\fP 1i
|
|
Specifies the property name.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XGetStandardColormap
|
|
function returns the colormap definition associated with the atom supplied
|
|
as the property argument.
|
|
.PN XGetStandardColormap
|
|
returns a nonzero status if successful and zero otherwise.
|
|
For example,
|
|
to fetch the standard
|
|
.PN GrayScale
|
|
colormap for a display,
|
|
you use
|
|
.PN XGetStandardColormap
|
|
with the following syntax:
|
|
.LP
|
|
.sM
|
|
.Ds 0
|
|
.TA .5i 1.5i
|
|
.ta .5i 1.5i
|
|
XGetStandardColormap(dpy, DefaultRootWindow(dpy), &cmap, XA_RGB_GRAY_MAP);
|
|
.De
|
|
.LP
|
|
.eM
|
|
See section 14.3 for the semantics of standard colormaps.
|
|
.LP
|
|
.PN XGetStandardColormap
|
|
can generate
|
|
.PN BadAtom
|
|
and
|
|
.PN BadWindow
|
|
errors.
|
|
.LP
|
|
.sp
|
|
To set a standard colormap, use
|
|
.PN XSetStandardColormap .
|
|
This function has been superseded by
|
|
.PN XSetRGBColormap .
|
|
.IN "XSetStandardColormap" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
XSetStandardColormap(\^\fIdisplay\fP, \fIw\fP, \fIcolormap\fP, \fIproperty\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
Window \fIw\fP\^;
|
|
.br
|
|
XStandardColormap *\fIcolormap\fP\^;
|
|
.br
|
|
Atom \fIproperty\fP\^; /* RGB_BEST_MAP, etc. */
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.IP \fIw\fP 1i
|
|
Specifies the window.
|
|
.IP \fIcolormap\fP 1i
|
|
Specifies the colormap.
|
|
.IP \fIproperty\fP 1i
|
|
Specifies the property name.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XSetStandardColormap
|
|
function usually is only used by window or session managers.
|
|
.LP
|
|
.PN XSetStandardColormap
|
|
can generate
|
|
.PN BadAlloc ,
|
|
.PN BadAtom ,
|
|
.PN BadDrawable ,
|
|
and
|
|
.PN BadWindow
|
|
errors.
|
|
.SH
|
|
Parsing Window Geometry
|
|
.LP
|
|
To parse window geometry given a user-specified position
|
|
and a default position, use
|
|
.PN XGeometry .
|
|
This function has been superseded by
|
|
.PN XWMGeometry .
|
|
.IN "Window" "determining location"
|
|
.IN "XGeometry" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
int XGeometry\^(\^\fIdisplay\fP, \fIscreen\fP, \fIposition\fP\^, \fIdefault_position\fP\^, \fIbwidth\fP\^, \fIfwidth\fP\^, \fIfheight\fP\^, \fIxadder\fP\^,
|
|
.br
|
|
\fIyadder\fP\^, \fIx_return\fP\^, \fIy_return\fP\^, \fIwidth_return\fP\^, \fIheight_return\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
int \fIscreen\fP\^;
|
|
.br
|
|
char *\fIposition\fP\^, *\fIdefault_position\fP\^;
|
|
.br
|
|
unsigned int \fIbwidth\fP\^;
|
|
.br
|
|
unsigned int \fIfwidth\fP\^, \fIfheight\fP\^;
|
|
.br
|
|
int \fIxadder\fP\^, \fIyadder\fP\^;
|
|
.br
|
|
int *\fIx_return\fP\^, *\fIy_return\fP\^;
|
|
.br
|
|
int *\fIwidth_return\fP\^, *\fIheight_return\fP\^;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.IP \fIscreen\fP 1i
|
|
Specifies the screen.
|
|
.IP \fIposition\fP 1i
|
|
.br
|
|
.ns
|
|
.IP \fIdefault_position\fP 1i
|
|
Specify the geometry specifications.
|
|
.IP \fIbwidth\fP 1i
|
|
Specifies the border width.
|
|
.IP \fIfheight\fP 1i
|
|
.br
|
|
.ns
|
|
.IP \fIfwidth\fP 1i
|
|
Specify the font height and width in pixels (increment size).
|
|
.IP \fIxadder\fP 1i
|
|
.br
|
|
.ns
|
|
.IP \fIyadder\fP 1i
|
|
Specify additional interior padding needed in the window.
|
|
.IP \fIx_return\fP 1i
|
|
.br
|
|
.ns
|
|
.IP \fIy_return\fP 1i
|
|
Return the x and y offsets.
|
|
.IP \fIwidth_return\fP 1i
|
|
.br
|
|
.ns
|
|
.IP \fIheight_return\fP 1i
|
|
Return the width and height determined.
|
|
.LP
|
|
.eM
|
|
You pass in the border width (bwidth),
|
|
size of the increments fwidth and fheight
|
|
(typically font width and height),
|
|
and any additional interior space (xadder and yadder)
|
|
to make it easy to compute the resulting size.
|
|
The
|
|
.PN XGeometry
|
|
function returns the position the window should be placed given a position and
|
|
a default position.
|
|
.PN XGeometry
|
|
determines the placement of
|
|
a window using a geometry specification as specified by
|
|
.PN XParseGeometry
|
|
and the additional information about the window.
|
|
Given a fully qualified default geometry specification and
|
|
an incomplete geometry specification,
|
|
.PN XParseGeometry
|
|
returns a bitmask value as defined above in the
|
|
.PN XParseGeometry
|
|
call,
|
|
by using the position argument.
|
|
.LP
|
|
The returned width and height will be the width and height specified
|
|
by default_position as overridden by any user-specified position.
|
|
They are not affected by fwidth, fheight, xadder, or yadder.
|
|
The x and y coordinates are computed by using the border width,
|
|
the screen width and height, padding as specified by xadder and yadder,
|
|
and the fheight and fwidth times the width and height from the
|
|
geometry specifications.
|
|
.SH
|
|
Getting the X Environment Defaults
|
|
.LP
|
|
The
|
|
.PN XGetDefault
|
|
function provides a primitive interface to the resource manager facilities
|
|
discussed in chapter 15.
|
|
It is only useful in very simple applications.
|
|
.LP
|
|
.sp
|
|
.IN "XGetDefault" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
char *XGetDefault\^(\^\fIdisplay\fP, \fIprogram\fP\^, \fIoption\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
char *\fIprogram\fP\^;
|
|
.br
|
|
char *\fIoption\fP\^;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.IP \fIprogram\fP 1i
|
|
Specifies the program name for the Xlib defaults (usually argv[0]
|
|
of the main program).
|
|
.IP \fIoption\fP 1i
|
|
Specifies the option name.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XGetDefault
|
|
function returns the value of the resource \fIprog\fP.\fIoption\fP,
|
|
where \fIprog\fP is the program argument with the directory prefix removed
|
|
and \fIoption\fP must be a single component.
|
|
Note that multilevel resources cannot be used with
|
|
.PN XGetDefault .
|
|
The class "Program.Name" is always used for the resource lookup.
|
|
If the specified option name does not exist for this program,
|
|
.PN XGetDefault
|
|
returns NULL.
|
|
The strings returned by
|
|
.PN XGetDefault
|
|
are owned by Xlib and should not be modified or freed by the client.
|
|
.LP
|
|
If a database has been set with
|
|
.PN XrmSetDatabase ,
|
|
that database is used for the lookup.
|
|
Otherwise, a database is created
|
|
and is set in the display (as if by calling
|
|
.PN XrmSetDatabase ).
|
|
The database is created in the current locale.
|
|
To create a database,
|
|
.PN XGetDefault
|
|
uses resources from the RESOURCE_MANAGER property on the root
|
|
window of screen zero.
|
|
If no such property exists,
|
|
a resource file in the user's home directory is used.
|
|
On a POSIX-conformant system,
|
|
this file is
|
|
.PN "$HOME/.Xdefaults" .
|
|
.IN "Files" "$HOME/.Xdefaults"
|
|
After loading these defaults,
|
|
.PN XGetDefault
|
|
merges additional defaults specified by the XENVIRONMENT
|
|
environment variable.
|
|
If XENVIRONMENT is defined,
|
|
it contains a full path name for the additional resource file.
|
|
If XENVIRONMENT is not defined,
|
|
.PN XGetDefault
|
|
looks for
|
|
.PN "$HOME/.Xdefaults-\fIname\fP" ,
|
|
where \fIname\fP specifies the name of the machine on which the application
|
|
is running.
|
|
.SH
|
|
X Version 10 Compatibility Functions
|
|
.LP
|
|
You can use the X Version 10 compatibility functions to:
|
|
.IP \(bu 5
|
|
Draw and fill polygons and curves
|
|
.IP \(bu 5
|
|
Associate user data with a value
|
|
.SH
|
|
Drawing and Filling Polygons and Curves
|
|
.LP
|
|
Xlib provides functions that you can use to draw or fill
|
|
arbitrary polygons or curves.
|
|
These functions are provided mainly for compatibility with X Version 10
|
|
and have no server support.
|
|
That is, they call other Xlib functions, not the server directly.
|
|
Thus, if you just have straight lines to draw, using
|
|
.PN XDrawLines
|
|
.IN "XDrawLines"
|
|
or
|
|
.PN XDrawSegments
|
|
.IN "XDrawSegments"
|
|
is much faster.
|
|
.LP
|
|
The functions discussed here provide all the functionality of the
|
|
X Version 10 functions
|
|
.PN XDraw ,
|
|
.IN "X10 compatibility" "XDraw"
|
|
.PN XDrawFilled ,
|
|
.IN "X10 compatibility" "XDrawFilled"
|
|
.PN XDrawPatterned ,
|
|
.IN "X10 compatibility" "XDrawPatterned"
|
|
.PN XDrawDashed ,
|
|
.IN "X10 compatibility" "XDrawDashed"
|
|
and
|
|
.PN XDrawTiled .
|
|
.IN "X10 compatibility" "XDrawTiled"
|
|
They are as compatible as possible given X Version 11's new line-drawing
|
|
functions.
|
|
One thing to note, however, is that
|
|
.PN VertexDrawLastPoint
|
|
is no longer supported.
|
|
Also, the error status returned is the opposite of what it was under
|
|
X Version 10 (this is the X Version 11 standard error status).
|
|
.PN XAppendVertex
|
|
and
|
|
.PN XClearVertexFlag
|
|
from X Version 10 also are not supported.
|
|
.LP
|
|
Just how the graphics context you use is set up actually
|
|
determines whether you get dashes or not, and so on.
|
|
Lines are properly joined if they connect and include
|
|
the closing of a closed figure (see
|
|
.PN XDrawLines ).
|
|
The functions discussed here fail (return zero) only if they run out of memory
|
|
or are passed a
|
|
.PN Vertex
|
|
list that has a
|
|
.PN Vertex
|
|
with
|
|
.PN VertexStartClosed
|
|
set that is not followed by a
|
|
.PN Vertex
|
|
with
|
|
.PN VertexEndClosed
|
|
set.
|
|
.LP
|
|
.sp
|
|
To achieve the effects of the X Version 10
|
|
.PN XDraw ,
|
|
.IN "X10 compatibility" "XDraw"
|
|
.PN XDrawDashed ,
|
|
.IN "X10 compatibility" "XDrawDashed"
|
|
and
|
|
.PN XDrawPatterned ,
|
|
.IN "X10 compatibility" "XDrawPatterned"
|
|
use
|
|
.PN XDraw .
|
|
.IN "XDraw" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
#include <X11/X10.h>
|
|
|
|
Status XDraw(\^\fIdisplay\fP, \fId\fP, \fIgc\fP, \fIvlist\fP, \fIvcount\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
Drawable \fId\fP\^;
|
|
.br
|
|
GC \fIgc\fP\^;
|
|
.br
|
|
Vertex *\fIvlist\fP\^;
|
|
.br
|
|
int \fIvcount\fP\^;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.IP \fId\fP 1i
|
|
Specifies the drawable.
|
|
.IP \fIgc\fP 1i
|
|
Specifies the GC.
|
|
.IP \fIvlist\fP 1i
|
|
Specifies a pointer to the list of vertices that indicate what to draw.
|
|
.IP \fIvcount\fP 1i
|
|
Specifies how many vertices are in vlist.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XDraw
|
|
function draws an arbitrary polygon or curve.
|
|
The figure drawn is defined by the specified list of vertices (vlist).
|
|
The points are connected by lines as specified in the flags in the
|
|
vertex structure.
|
|
.LP
|
|
Each Vertex, as defined in
|
|
.hN X11/X10.h ,
|
|
is a structure with the following members:
|
|
.LP
|
|
.IN "Vertex" "" "@DEF@"
|
|
.sM
|
|
.Ds 0
|
|
.TA .5i 1.5i
|
|
.ta .5i 1.5i
|
|
typedef struct _Vertex {
|
|
short x,y;
|
|
unsigned short flags;
|
|
} Vertex;
|
|
.De
|
|
.LP
|
|
.eM
|
|
The x and y members are the coordinates of the vertex
|
|
that are relative to either the upper left inside corner of the drawable
|
|
(if
|
|
.PN VertexRelative
|
|
is zero) or the previous vertex (if
|
|
.PN VertexRelative
|
|
is one).
|
|
.LP
|
|
The flags, as defined in
|
|
.hN X11/X10.h ,
|
|
are as follows:
|
|
.IN "VertexRelative" "" "@DEF@"
|
|
.IN "VertexDontDraw" "" "@DEF@"
|
|
.IN "VertexCurved" "" "@DEF@"
|
|
.IN "VertexStartClosed" "" "@DEF@"
|
|
.IN "VertexEndClosed" "" "@DEF@"
|
|
.sM
|
|
.TS
|
|
l l l.
|
|
T{
|
|
.PN VertexRelative
|
|
T} T{
|
|
0x0001
|
|
T} T{
|
|
/* else absolute */
|
|
T}
|
|
T{
|
|
.PN VertexDontDraw
|
|
T} T{
|
|
0x0002
|
|
T} T{
|
|
/* else draw */
|
|
T}
|
|
T{
|
|
.PN VertexCurved
|
|
T} T{
|
|
0x0004
|
|
T} T{
|
|
/* else straight */
|
|
T}
|
|
T{
|
|
.PN VertexStartClosed
|
|
T} T{
|
|
0x0008
|
|
T} T{
|
|
/* else not */
|
|
T}
|
|
T{
|
|
.PN VertexEndClosed
|
|
T} T{
|
|
0x0010
|
|
T} T{
|
|
/* else not */
|
|
T}
|
|
.TE
|
|
.LP
|
|
.eM
|
|
.IP \(bu 5
|
|
If
|
|
.PN VertexRelative
|
|
is not set,
|
|
the coordinates are absolute (that is, relative to the drawable's origin).
|
|
The first vertex must be an absolute vertex.
|
|
.IP \(bu 5
|
|
If
|
|
.PN VertexDontDraw
|
|
is one,
|
|
no line or curve is drawn from the previous vertex to this one.
|
|
This is analogous to picking up the pen and moving to another place
|
|
before drawing another line.
|
|
.IP \(bu 5
|
|
If
|
|
.PN VertexCurved
|
|
is one,
|
|
a spline algorithm is used to draw a smooth curve from the previous vertex
|
|
through this one to the next vertex.
|
|
Otherwise, a straight line is drawn from the previous vertex to this one.
|
|
It makes sense to set
|
|
.PN VertexCurved
|
|
to one only if a previous and next vertex are both defined
|
|
(either explicitly in the array or through the definition of a closed
|
|
curve).
|
|
.IP \(bu 5
|
|
It is permissible for
|
|
.PN VertexDontDraw
|
|
bits and
|
|
.PN VertexCurved
|
|
bits both to be one.
|
|
This is useful if you want to define the previous point for the smooth curve
|
|
but do not want an actual curve drawing to start until this point.
|
|
.IP \(bu 5
|
|
If
|
|
.PN VertexStartClosed
|
|
is one,
|
|
then this point marks the beginning of a closed curve.
|
|
This vertex must be followed later in the array by another vertex
|
|
whose effective coordinates are identical
|
|
and that has a
|
|
.PN VertexEndClosed
|
|
bit of one.
|
|
The points in between form a cycle to determine predecessor
|
|
and successor vertices for the spline algorithm.
|
|
.LP
|
|
This function uses these GC components:
|
|
function, plane-mask, line-width, line-style, cap-style, join-style,
|
|
fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and
|
|
clip-mask.
|
|
It also uses these GC mode-dependent components:
|
|
foreground, background, tile, stipple,
|
|
tile-stipple-x-origin, tile-stipple-y-origin, dash-offset, and dash-list.
|
|
.LP
|
|
.sp
|
|
To achieve the effects of the X Version 10
|
|
.PN XDrawTiled
|
|
.IN "X10 compatibility" "XDrawTiled"
|
|
and
|
|
.PN XDrawFilled ,
|
|
.IN "X10 compatibility" "XDrawFilled"
|
|
use
|
|
.PN XDrawFilled .
|
|
.IN "XDrawFilled" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
#include <X11/X10.h>
|
|
|
|
Status XDrawFilled(\^\fIdisplay\fP, \fId\fP, \fIgc\fP, \fIvlist\fP, \fIvcount\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
Drawable \fId\fP\^;
|
|
.br
|
|
GC \fIgc\fP\^;
|
|
.br
|
|
Vertex *\fIvlist\fP\^;
|
|
.br
|
|
int \fIvcount\fP\^;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.IP \fId\fP 1i
|
|
Specifies the drawable.
|
|
.IP \fIgc\fP 1i
|
|
Specifies the GC.
|
|
.IP \fIvlist\fP 1i
|
|
Specifies a pointer to the list of vertices that indicate what to draw.
|
|
.IP \fIvcount\fP 1i
|
|
Specifies how many vertices are in vlist.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XDrawFilled
|
|
function draws arbitrary polygons or curves and then fills them.
|
|
.LP
|
|
This function uses these GC components:
|
|
function, plane-mask, line-width, line-style, cap-style, join-style,
|
|
fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and
|
|
clip-mask.
|
|
It also uses these GC mode-dependent components:
|
|
foreground, background, tile, stipple,
|
|
tile-stipple-x-origin, tile-stipple-y-origin,
|
|
dash-offset, dash-list, fill-style, and fill-rule.
|
|
.SH
|
|
Associating User Data with a Value
|
|
.LP
|
|
These functions have been superseded by the context management functions
|
|
(see section 16.10).
|
|
It is often necessary to associate arbitrary information with resource IDs.
|
|
Xlib provides the
|
|
.PN XAssocTable
|
|
functions that you can use to make such an association.
|
|
.IN "Hash Lookup"
|
|
.IN "Window" "IDs"
|
|
.IN "Resource IDs"
|
|
Application programs often need to be able to easily refer to
|
|
their own data structures when an event arrives.
|
|
The
|
|
.PN XAssocTable
|
|
system provides users of the X library with a method
|
|
for associating their own data structures with X resources
|
|
.Pn ( Pixmaps ,
|
|
.PN Fonts ,
|
|
.PN Windows ,
|
|
and so on).
|
|
.LP
|
|
An
|
|
.PN XAssocTable
|
|
can be used to type X resources.
|
|
For example, the user
|
|
may want to have three or four types of windows,
|
|
each with different properties.
|
|
This can be accomplished by associating each X window ID
|
|
with a pointer to a window property data structure defined by the
|
|
user.
|
|
A generic type has been defined in the X library for resource IDs.
|
|
It is called an XID.
|
|
.LP
|
|
There are a few guidelines that should be observed when using an
|
|
.PN XAssocTable :
|
|
.IP \(bu 5
|
|
All XIDs are relative to the specified display.
|
|
.IP \(bu 5
|
|
Because of the hashing scheme used by the association mechanism,
|
|
the following rules for determining the size of a
|
|
.PN XAssocTable
|
|
should be followed.
|
|
Associations will be made and looked up more
|
|
efficiently if the table size (number of buckets in the hashing
|
|
system) is a power of two and if there are not more than 8 XIDs per
|
|
bucket.
|
|
.LP
|
|
.sp
|
|
To return a pointer to a new
|
|
.PN XAssocTable ,
|
|
use
|
|
.PN XCreateAssocTable .
|
|
.IN "XCreateAssocTable" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
XAssocTable *XCreateAssocTable\^(\^\fIsize\fP\^)
|
|
.br
|
|
int \fIsize\fP\^;
|
|
.FN
|
|
.IP \fIsize\fP 1i
|
|
Specifies the number of buckets in the hash system of
|
|
.PN XAssocTable .
|
|
.LP
|
|
.eM
|
|
The size argument specifies the number of buckets in the
|
|
hash system of
|
|
.PN XAssocTable .
|
|
For reasons of efficiency the number of buckets
|
|
should be a power of two.
|
|
Some size suggestions might be: use 32 buckets per 100 objects,
|
|
and a reasonable maximum number of objects per buckets is 8.
|
|
If an error allocating memory for the
|
|
.PN XAssocTable
|
|
occurs,
|
|
a NULL pointer is returned.
|
|
.LP
|
|
.sp
|
|
To create an entry in a given
|
|
.PN XAssocTable ,
|
|
use
|
|
.PN XMakeAssoc .
|
|
.IN "XMakeAssoc" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
XMakeAssoc\^(\^\fIdisplay\fP, \fItable\fP\^, \fIx_id\fP\^, \fIdata\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
XAssocTable *\fItable\fP\^;
|
|
.br
|
|
XID \fIx_id\fP\^;
|
|
.br
|
|
char *\fIdata\fP\^;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.IP \fItable\fP 1i
|
|
Specifies the assoc table.
|
|
.IP \fIx_id\fP 1i
|
|
Specifies the X resource ID.
|
|
.IP \fIdata\fP 1i
|
|
Specifies the data to be associated with the X resource ID.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XMakeAssoc
|
|
function inserts data into an
|
|
.PN XAssocTable
|
|
keyed on an XID.
|
|
Data is inserted into the table only once.
|
|
Redundant inserts are ignored.
|
|
The queue in each association bucket is sorted from the lowest XID to
|
|
the highest XID.
|
|
.LP
|
|
.sp
|
|
To obtain data from a given
|
|
.PN XAssocTable ,
|
|
use
|
|
.PN XLookUpAssoc .
|
|
.IN "XLookUpAssoc" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
char *XLookUpAssoc\^(\^\fIdisplay\fP, \fItable\fP\^, \fIx_id\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
XAssocTable *\fItable\fP\^;
|
|
.br
|
|
XID \fIx_id\fP\^;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.IP \fItable\fP 1i
|
|
Specifies the assoc table.
|
|
.IP \fIx_id\fP 1i
|
|
Specifies the X resource ID.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XLookUpAssoc
|
|
function retrieves the data stored in an
|
|
.PN XAssocTable
|
|
by its XID.
|
|
If an appropriately matching XID can be found in the table,
|
|
.PN XLookUpAssoc
|
|
returns the data associated with it.
|
|
If the x_id cannot be found in the table,
|
|
it returns NULL.
|
|
.LP
|
|
.sp
|
|
To delete an entry from a given
|
|
.PN XAssocTable ,
|
|
use
|
|
.PN XDeleteAssoc .
|
|
.IN "XDeleteAssoc" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
XDeleteAssoc\^(\^\fIdisplay\fP, \fItable\fP\^, \fIx_id\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
XAssocTable *\fItable\fP\^;
|
|
.br
|
|
XID \fIx_id\fP\^;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.IP \fItable\fP 1i
|
|
Specifies the assoc table.
|
|
.IP \fIx_id\fP 1i
|
|
Specifies the X resource ID.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XDeleteAssoc
|
|
function deletes an association in an
|
|
.PN XAssocTable
|
|
keyed on its XID.
|
|
Redundant deletes (and deletes of nonexistent XIDs) are ignored.
|
|
Deleting associations in no way impairs the performance of an
|
|
.PN XAssocTable .
|
|
.LP
|
|
.sp
|
|
To free the memory associated with a given
|
|
.PN XAssocTable ,
|
|
use
|
|
.PN XDestroyAssocTable .
|
|
.IN "XDestroyAssocTable" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
XDestroyAssocTable\^(\^\fItable\fP\^)
|
|
.br
|
|
XAssocTable *\fItable\fP\^;
|
|
.FN
|
|
.IP \fItable\fP 1i
|
|
Specifies the assoc table.
|
|
.LP
|
|
.eM
|
|
.bp
|