[Search for users]
[Overall Top Noters]
[List of all Conferences]
[Download this site]
Title: | DECWINDOWS 26-JAN-89 to 29-NOV-90 |
Notice: | See 1639.0 for VMS V5.3 kit; 2043.0 for 5.4 IFT kit |
Moderator: | STAR::VATNE |
|
Created: | Mon Oct 30 1989 |
Last Modified: | Mon Dec 31 1990 |
Last Successful Update: | Fri Jun 06 1997 |
Number of topics: | 3726 |
Total number of notes: | 19516 |
936.0. "Proposed changes to Xlib for ICCCM support" by MIPSBX::thomas (The Code Warrior) Tue Jun 13 1989 14:38
Xlib Proposal: ICCCM Support
1. Introduction
This proposal outlines changes to the Xlib data structures and programming
interfaces to support the Inter-Client Communication Conventions Manual.
This proposal is being published for Public Review. The proposal is only a
draft proposal of the MIT X Consortium and is therefore subject to change.
The objective of Public Review is to determine if the current draft is
acceptable as a change to the Consortium Xlib standard. Public Review can
result in changes to the draft. Public Review is scheduled to end July 21.
The X community is encouraged to review the draft and submit comments by
electronic mail to
[email protected]
Comments sent to other addresses are not guaranteed to be considered.
2. Data Structures and Constants
This section describes additions to the XSizeHints and XStandardColormap data
structures and the introduction of a new structure for manipulating properties
containing text.
2.1. XSizeHints
Three new elements have been added to properties of type WM_SIZE_HINTS:
base_width, base_height, and win_gravity. Fields containing these values can
be added to the end of the existing XSizeHints structure (defined in Xutil.h)
without disrupting any existing interfaces. Since all three of these fields
represent small numbers, these fields can safely be of type "int" (which fits
in better with the declarations of the other fields):
typedef struct {
long flags; /* marks which fields are defined */
int x, y; /* OBSOLETE */
int width, height; /* OBSOLETE */
int min_width, min_height;
int max_width, max_height;
int width_inc, height_inc;
struct {
int x; /* numerator */
int y; /* denominator */
} min_aspect, max_aspect;
int base_width, base_height; /* NEW */
int win_gravity; /* NEW */
} XSizeHints;
The x, y, width, and height fields are now obsolete, but should be left for
compatibility.
Two size hints flags to describe the new fields should be added to Xutil.h:
#define PBaseSize (1L << 8)
#define PWinGravity (1L << 9)
Use of the macro PAllHints should be strongly discouraged. In addition, the
XGetSizeHints and XSetSizeHints routines (and those built on top of them)
should be changed to mask out unwanted bits.
2.2. XStandardColormap
Two new elements have been added to properties of type RGB_COLOR_MAP: the id of
the visual from which the colormap was created and an arbitrary resource id
that indicates whether or not the cells held by this standard colormap should
be released by freeing the colormap id or by doing a KillClient on the
indicated resource (necessary for allocating out of an existing map). These
fields can be added to the end of the existing structure (defined in Xutil.h)
without disrupting the existing interfaces:
typedef struct {
Colormap colormap;
unsigned long red_max;
unsigned long red_mult;
unsigned long green_max;
unsigned long green_mult;
unsigned long blue_max;
unsigned long blue_mult;
unsigned long base_pixel;
VisualID visualid; /* NEW */
XID killid; /* NEW */
} XStandardColormap;
In addition, a new symbolic value indicating that the resources should be
released by freeing the colormap needs to be added to Xutil.h:
#define ReleaseByFreeingColormap ((XID) 1L)
2.3. XTextProperty
Many of the properties that used to be of type STRING have been changed to
allow a variety of types and formats. Since the data stored in these
properties are no longer simple null-terminated strings, a new data structure
is necessary to describe the encoding, type, and length of the text as well as
its value. The following structure should be added to Xutil.h:
typedef struct {
unsigned char *value; /* property data */
Atom encoding; /* type of property */
int format; /* 8, 16, or 32 */
unsigned long nitems; /* number of items in value */
} XTextProperty;
2.4. WM_STATE property
Since the contents of the WM_STATE property are undefined, no interfaces for
getting or setting the property will be provided. However, a constant for
specifying the withdrawn window state is needed in Xutil.h:
#define WithdrawnState 0
3. Internal Implementation Issues
For compatibility with existing clients, the pre-ICCCM interfaces for accessing
WM_SIZE_HINTS and RGB_COLOR_MAP properties should be retained. In particular,
the new fields in the XSizeHints and XStandardColormap and their corresponding
properties must never be referenced. Applications that are relinked against a
new library should not see any change in behavior. This affects the following
routines:
XGetSizeHints XSetSizeHints
XGetNormalHints XSetNormalHints
XGetStandardColormap XSetStandardColormap
4. New Programming Interfaces for ICCCM
The following interfaces should be added to Xlib.
4.1. Allocating Structures for Property Data
The following routines are used to allocate memory for the various data
structures reflecting information stored in properties. By allocating
these structures at run time, instead of declaring them at compile time,
clients will avoid memory overwriting problems should additional fields
ever be added to these structures.
XSizeHints *XAllocSizeHints ()
XStandardColormap *XAllocStandardColormap ()
XWMHints *XAllocWMHints ()
XClassHint *XAllocClassHint ()
XIconSize *XAllocIconSize ()
The XAllocSizeHints, XAllocStandardColormap, XAllocWMHints,
XAllocClassHint, and XAllocIconSize routines allocate and return
pointers to XSizeHints, XStandardColormap, XWMHints, XClassHint, and
XIconSize structures, respectively. Pointer fields will be set to
NULL and all other fields will be set to zero. If sufficient memory
isn't available, NULL will be returned. The storage for the
structures returned by these routines can be released with XFree.
4.2. Manipulating Top-Level Windows
The following routines are used to change the size or visibility of top-level
windows (created as children of the root window).
Status XIconifyWindow (dpy, w, screen)
Display *dpy;
Window w;
int screen;
The XIconifyWindow function sends a WM_CHANGE_STATE ClientMessage event
with a format of 32 and a first data element of IconicState (as
described in Section 4.1.4, Changing Window State, in the ICCCM) to the
root window of the specified screen. Window managers may elect to
receive this message and, if the window is in its normal state, may
treat it as a request to change the window's state from normal to
iconic. If the atom WM_CHANGE_STATE cannot be interned, no message is
sent, and a status of 0 is returned. A non-zero status is returned if
the client message is sent successfully; otherwise, a status of 0 is
returned.
XIconifyWindow can generate a BadWindow error.
Status XWithdrawWindow (dpy, w, screen)
Display *dpy;
Window w;
int screen;
The XWithdrawWindow function unmaps the specified window and sends a
synthetic UnmapNotify event to the root window of the specified screen.
Window managers may elect to receive this message and treat it as a
request to change the window's state to withdrawn. When a window is in
the withdrawn state, neither its normal nor its iconic representations
is visible. A non-zero status is returned if the UnmapNotify event is
sent successfully; otherwise, a 0 is returned.
XWithdrawWindow can generate a BadWindow error.
Status XReconfigureWMWindow (dpy, w, screen, mask, changes)
Display *dpy;
Window w;
int screen;
unsigned int mask;
XWindowChanges *changes;
The XReconfigureWMWindow function does a ConfigureWindow on the
specified top-level window. If the stacking mode is changed and the
request fails with a BadMatch error, the error event is trapped and a
synthetic ConfigureRequestEvent containing the same configuration
parameters is sent to the root of the specified window. Window
managers may elect to receive this event and treat it as a request to
reconfigure the indicated window.
XReconfigureWMWindow can generate BadValue and BadWindow errors.
4.3. String Lists
The following routines are used to convert between lists of pointers to
character strings and text properties.
Status XStringListToTextProperty (list, count, text_prop_return)
char **list;
int count;
XTextProperty *text_prop_return;
The XStringListToTextProperty function sets the specified XTextProperty
to be of type STRING (format 8) with a value representing the
concatenation of the specified list of null-separated character
strings. An extra byte containing NUL (but which is not included in
the nitems count) is allocated for the value field of text_prop_return.
Storage for this field may be released using XFree. If insufficient
memory is available for the new new value string, none of the fields in
text_prop_return are set and 0 is returned. Otherwise, a non-zero
status is returned.
Status XTextPropertyToStringList (text_prop, list_return, count_return)
XTextProperty *text_prop;
char ***list_return;
int *count_return;
The XTextPropertyToStringList function returns a list of strings
representing the null-separated elements of text_prop. The data in
text_prop must be of type STRING and format 8; multiple elements (such
as the strings in a disjoint text selection) are separated by a NUL
(encoding 0). The property is not null-terminated. Storage for the
list and its contents may be released using XFreeStringList. If
insufficient memory is available for the list and its elements, neither
of the return values is set and a status of 0 is returned. Otherwise,
a non-zero status is returned.
void XFreeStringList (list)
char **list;
The XFreeStringList function releases memory allocated by
XTextPropertyToStringList.
4.4. Manipulating Text Properties
The following routines are used to get and set information on properties which
are intended to hold text. Note that Xlib does not enforce any particular
encoding of textual information.
Status XGetTextProperty (display, window, text_prop_return, property)
Display *display;
Window window;
XTextProperty *text_prop_return;
Atom property;
The XGetTextProperty function reads the specified property from the
window and stores the data in the value field of text_prop_return, the
type of the data in the encoding field, the format of the data in the
format field, and the number of items of data in the nitems field. The
particular interpretation of the property's encoding and data as
``text'' is left to the calling application.
If the property does not exist on the window, the value field of
text_prop_return is set to NULL, the encoding field is set
to None, the format field is set to 0, and the nitems field is
set to 0.
The function returns a non-zero status if it was able to set the
fields of text_prop_return, otherwise it returns 0.
XGetTextProperty can generate BadWindow and BadAtom errors.
Status XGetWMName (dpy, w, text_prop_return)
Status XGetWMIconName (dpy, w, text_prop_return)
Status XGetWMClientMachine (dpy, w, text_prop_return)
Display *dpy;
Window w;
XTextProperty *text_prop_return;
The XGetWMName, XGetWMIconName, and XGetWMClientMachine
functions are convenience routines which perform an XGetTextProperty
on the properties WM_NAME, WM_ICON_NAME, WM_CLIENT_MACHINE,
respectively.
XGetWMName supersedes XFetchName. XGetWMIconName supersedes
XGetIconName.
void XSetTextProperty (dpy, w, text_prop, property)
Display *dpy;
Window w;
XTextProperty *text_prop;
Atom property;
The XSetTextProperty routine replaces (or sets if the property does not
exist) the specified property for the indicated window with the data
given by the value field of text_prop, the type given by the
encoding field, the format given by the format field, and the
number of items given by the nitems field.
XSetTextProperty can generate BadWindow, BadAtom, BadValue, and
BadAlloc errors.
void XSetWMName (dpy, w, text_prop)
void XSetWMIconName (dpy, w, text_prop)
void XSetWMClientMachine (dpy, w, text_prop)
Display *dpy;
Window w;
XTextProperty *text_prop;
XSetWMName, XSetWMIconName, and XSetWMClientMachine
are convenience routines which perform an XSetTextProperty on the
properties WM_NAME, WM_ICON_NAME, and WM_CLIENT_MACHINE,
respectively.
XSetWMName supersedes XStoreName. XSetWMIconName supersedes
XSetIconName.
Status XGetCommand (dpy, w, argvp, argcp)
Display *dpy;
Window w;
char ***argvp;
int *argcp;
The XGetCommand function reads the WM_COMMAND property from the
specified window and returns a string list. If the WM_COMMAND property
exists, is of type STRING and format 8, and if there is enough
enough memory to contain the string list, the argvp and argc fields are
filled in with a string list that may be freed with XFreeStringList and
a non-zero status is returned. Otherwise, a 0 status is returned.
4.5. Size Hints
The following routines are used for getting and setting size hints:
Status XGetWMSizeHints (dpy, w, hints_return, supplied_return, property)
Display *dpy;
Window w;
XSizeHints *hints_return;
long *supplied_return;
Atom property;
The XGetWMSizeHints function returns the size hints stored in the
indicated property on the specified window. If the property is of type
WM_SIZE_HINTS and format 32 and is long enough to contain either an old
(pre-ICCCM) or new size hints structure, the various fields of the
hints_return structure are set, supplied_return is set to contain the
list of fields that were supplied by the user (whether or not the
contained defined values) and a non-zero status is returned.
Otherwise, a status of 0 is returned. To get a window's normal size
hints, the routine XGetWMNormalHints may be used instead.
If the routine returns successfully, supplied_return will contain
the following bits if a pre-ICCCM size hints property is read:
(USPosition|USSize|PPosition|PSize|PMinSize|
PMaxSize|PResizeInc|PAspect)
If the property is large enough to contain the base size and window
gravity fields as well, supplied_return will have PBaseSize and
PWinGravity set as well.
XGetWMSizeHints can generate BadWindow and BadAtom errors.
XGetWMSizeHints supersedes XGetSizeHints.
void XSetWMSizeHints (dpy, w, hints, property)
Display *dpy;
Window w;
XSizeHints *hints;
Atom property;
The XSetWMSizeHints function replaces (or sets if the property does not
exist) the size hints for indicated property on the specified window.
The property is stored with a type of WM_SIZE_HINTS and a format of 32.
To set a window's normal size hints, the routine XSetWMNormalHints may
be used instead.
XSetWMSizeHints can generate BadWindow, BadAtom, and BadAlloc errors.
XSetWMSizeHints supersedes XSetSizeHints.
Status XGetWMNormalHints (dpy, w, hints_return, supplied_return)
Display *dpy;
Window w;
XSizeHints *hints_return;
long *supplied_return;
The XGetWMNormalHints function returns the size hints stored in the
WM_NORMAL_HINTS property on the specified window. If the property is
of type WM_SIZE_HINTS and format 32 and is long enough to contain
either an old (pre-ICCCM) or new size hints structure, the various
fields of the hints_return structure are set, supplied_return is set to
contain the list of fields that were supplied by the user (whether or
not the contained defined values) and a non-zero status is returned.
Otherwise, a status of 0 is returned.
If the routine returns successfully, supplied_return will contain
the following bits if a pre-ICCCM size hints property is read:
(USPosition|USSize|PPosition|PSize|PMinSize|
PMaxSize|PResizeInc|PAspect)
If the property is large enough to contain the base size and window
gravity fields as well, supplied_return will have PBaseSize and
PWinGravity set as well.
XGetWMNormalHints can generate a BadWindow error.
XGetWMNormalHints supersedes XGetNormalHints.
void XSetWMNormalHints (dpy, w, hints)
Display *dpy;
Window w;
XSizeHints *hints;
The XSetWMNormalHints function replaces (or sets if the property does
not exist) the size hints for the WM_NORMAL_HINTS property on the
specified window. The property is stored with a type of WM_SIZE_HINTS
and a format of 32.
XSetWMNormalHints can generate BadWindow and BadAlloc errors.
XSetWMNormalHints supersedes XSetNormalHints.
4.6. Window Manager Protocols List
The following routines are used to get and set the list of window manager
protocols in which the client is willing to participate:
Status XGetWMProtocols (dpy, w, protocols_return, count_return)
Display *dpy;
Window w;
Atom **protocols_return;
int *count_return;
The XGetWMProtocols function returns the list of atoms stored in the
WM_PROTOCOLS property on the specified window. These atoms describe
window manager protocols in which the owner of this window is willing
to participate. If the property exists, is of type ATOM, is of format
32, and the atom WM_PROTOCOLS can be interned, protocols_return is set
to a list (which the caller may release with XFree) of atoms,
count_return is set to the number of elements in list, and a non-zero
status is returned. Otherwise, a status of 0 is returned and neither
of the return values is set.
XGetWMProtocols can generate a BadWindow error.
Status XSetWMProtocols (dpy, w, protocols, count)
Display *dpy;
Window w;
Atom *protocols;
int count;
The XSetWMProtocols routine replaces (or sets if the property does not
exist) the WM_PROTOCOLS property on the specified window to contain the
list of atoms given by protocols. The property is stored with a type
of ATOM and a format of 32. If the routine is unable to intern the
atom WM_PROTOCOLS, a status of 0 will be returned. Otherwise, a
non-zero status is returned.
XSetWMProtocols can generate BadWindow and BadAlloc errors.
4.7. Window Manager Colormap Windows List
The following routines are used to get and set the list of windows whose
colormaps should be installed by the window manager:
Status XGetWMColormapWindows (dpy, w, windows_return, count_return)
Display *dpy;
Window w;
Window **windows_return;
int *count_return;
The XGetWMColormapWindows function returns the list of window
identifiers stored in the WM_COLORMAP_WINDOWS property on the specified
window. These windows indicate the colormaps that the window manager
may need to install for this window. If the property exists, is of
type WINDOW, is of format 32, and the atom WM_COLORMAP_WINDOWS can
be interned, windows_return is set to a list (which the caller may
release with XFree) of window identifiers, count_return is set to the
number of elements in list, and a non-zero status is returned.
Otherwise, a status of 0 is returned and neither of the return values
is set.
XGetWMColormapWindows can generate a BadWindow error.
Status XSetWMColormapWindows (dpy, w, colormap_windows, count)
Display *dpy;
Window w;
Windows *colormap_windows;
int count;
The XSetWMColormapWindows routine replaces (or sets if the property
does not exist) the WM_COLORMAP_WINDOWS property on the specified
window to contain the list of windows given by colormap_windows. The
property is stored with a type of WINDOW and a format of 32. If
the routine is unable to intern the atom WM_COLORMAP_WINDOWS, a status
of 0 will be returned. Otherwise, a non-zero status is returned.
XSetWMColormapWindows can generate BadWindow and BadAlloc errors.
4.8. Standard Colormaps
The following functions are used to get and set standard colormaps:
Status XGetRGBColormaps (dpy, w, stdcmap_return, count_return, property)
Display *dpy;
Window w;
XStandardColormap **stdcmap_return;
int *count_return;
Atom property;
The XGetRGBColormaps function returns the RGB colormap definitions
stored in the indicated property on the specified window. If the
property exists, is of type RGB_COLOR_MAP, is of format 32, and is long
enough to contain a colormap definition (if the visualid is not
present, the default visual for the screen on which the window is
located is assumed; if the killid is not present, None, indicating that
the resources cannot be released, is assumed), space for the returned
colormaps is allocated and is filled in, and a non-zero status is
returned. Otherwise, none of the fields are set and a status of 0 is
returned. It is the caller's responsibility to honor the ICCCM's
restriction that only RGB_DEFAULT_MAP contain more than one definition.
XGetRGBColormaps can generate BadWindow and BadAtom errors.
XGetRGBColormaps supersedes XGetStandardColormap.
void XSetRGBColormaps (dpy, w, stdcmap, count, property)
Display *dpy;
Window w;
XStandardColormap *stdcmap;
int count;
Atom property;
The XSetRGBColormaps routine replaces (or sets if the property does not
exist) the RGB colormap definition in the indicated property on the
specified window. The property is stored with a type of RGB_COLOR_MAP
and a format of 32. It is the caller's responsibility to honor the
ICCCM's restriction that only RGB_DEFAULT_MAP contain more than one
definition.
XSetRGBColormap can generate BadWindow, BAdAtom, and BadAlloc errors.
XSetRGBColormap supersedes XSetStandardColormap.
4.9. Convenience Routines
The following routines provide convenient interfaces to the new property
formats:
void XSetWMProperties (dpy, w, window_name, icon_name, argv, argc,
normal_hints, wm_hints)
Display *dpy; /* user's display connection */
Window w; /* window to decorate */
XTextProperty *window_name; /* name of application */
XTextProperty *icon_name; /* name string for icon */
char **argv; /* command line */
int argc; /* size of command line */
XSize_hints *normal_hints; /* size hints in normal state */
XWM_hints *wm_hints; /* miscellaneous window manager hints */
The XSetWMProperties routine provides a convenient interface for
setting the most essential properties on the specified window for
communicating with other clients (particularly window and session
managers).
If window_name is non-null, the WM_NAME property is set using
XSetWMName. If icon_name is non-null, WM_ICON_NAME is set using
XSetWMIconName. If argv is non-null, WM_COMMAND is set using
XSetCommand (note that an argc of 0 is allowed to indicate a
zero-length command). The hostname of this machine is stored using
XSetWMClientMachine. If normal_hints is non-null, WM_NORMAL_HINTS is
set using XSetWMNormalHints. If wm_hints is non-null, WM_HINTS is
set using XSetWMHints.
XSetWMProperties can return any of errors generated by the
routines mentioned above.
XSetWMProperties supersedes XSetStandardProperties.
int XWMGeometry (dpy, screen, user_geom, def_geom, bwidth, hints,
x_return, y_return, width_return, height_return,
gravity_return)
Display *dpy; /* user's display connection */
int screen; /* screen on which to do computation */
char *user_geom; /* user geometry or NULL */
char *def_geom; /* program default geometry or NULL */
unsigned int bwidth; /* border width */
XSizeHints *hints; /* usually WM_NORMAL_HINTS */
int *x_return, *y_return; /* location; set on successful ret */
int *width_return; /* size; set on successful return */
int *height_return; /* size; set on successful return */
int *gravity_return; /* gravity for these coordinates */
The XWMGeometry function combines any geometry information (given in
the format used by XParseGeometry) specified by the user and by the
calling program with size hints (usually the ones to be stored in
WM_NORMAL_HINTS) and returns the position, size, and gravity
(NorthWestGravity, NorthEastGravity, SouthEastGravity or
SouthWestGravity) describing the window. If the base size is not set
in the hints structure, then the minimum size will be used if set.
Otherwise, a base size of 0 is assumed. If no minimum size is set in
the hints structure, the base size will be used. A mask of the form
returned by XParseGeometry, describing which values came from the user
specification and whether or not the position coordinates are relative
to the right and bottom edges is returned (which will have already been
accounted for in the x_return and y_return values).
Invalid geometry specifications may cause a width or height of 0 to
be returned. The caller may pass the address of the hints win_gravity
field as gravity_return to update the hints directly.
XWMGeometry supersedes XGeometry.
5. Obsolete Functions
The following functions in Xlib should be moved to an appendix as they are
now obsolete:
XGetSizeHints superseded by XGetWMSizeHints
XGetNormalHints superseded by XGetWMNormalHints
XSetSizeHints superseded by XSetWMSizeHints
XSetNormalHints superseded by XSetWMNormalHints
XGetStandardColormap superseded by XGetRGBColormap
XSetStandardColormap superseded by XSetRGBColormap
XSetStandardProperties superseded by XSetWMProperties
XGeometry superseded by XWMGeometry
XGetZoomHints no longer supported by ICCCM
XSetZoomHints no longer supported by ICCCM
The following constants should be marked obsolete in Xutil.h:
DontCareState no longer supported by ICCCM
ZoomState no longer supported by ICCCM
InactiveState no longer supported by ICCCM
The following functions should be marked as convenience function for window
and icon names that are encoded as STRING properties:
XFetchName generalized by XGetWMName
XGetIconName generalized by XGetWMIconName
XStoreName generalized by XSetWMName
XSetIconName generalized by XSetWMIconName
T.R | Title | User | Personal Name | Date | Lines |
---|
936.1 | ICCCM availability | STAR::CYPRYCH | | Wed Jun 14 1989 09:58 | 4 |
| Please be aware that if you try most of these on SDC
kits it isnt available yet. ICCCM didn't close its
final phase of reviews until a few weeks ago...
|
936.2 | How about iconify/expand | GR8FUL::HERBERT | Class B Computing Device | Wed Jun 14 1989 14:09 | 6 |
| Can you say what functions the window manager does support? For
instance, does the window manager support the ClientMessage to
request a window to iconify?
Kevin
|
936.3 | | GOSOX::RYAN | DECwindows Mail | Thu Jun 15 1989 07:58 | 4 |
| Is the final ICCCM available? Where?
Mike
|
936.4 | Implementation of ICCCM iconify | STAR::CYPRYCH | | Thu Jun 15 1989 11:23 | 13 |
| RE: .2
The DEC window manager supported a way to iconify, before ICCCM
invented a way. That support will not be removed before the ICCCM
mechanism for iconifying a window is implemented. Currently,
the intention is to leave the DEC supported way intact even
if ICCCM support is there also. Also, the ICCCM support
for iconifying a window does not exist in the DEC window manager
SDC kit.
There are several notes in this notesfile and in decwindows programming
notesfile which discuss how to do this.
|
936.5 | Note 131 | 17305::WEST | I'm just visiting this planet. | Thu Jun 15 1989 12:48 | 7 |
| RE: .2
The one I know off hand is note 131 in this notes file.
-=> Jim <=-
|
936.6 | | TRNSAM::HOLT | Robert Holt ISV Atelier West | Wed Jan 03 1990 16:12 | 4 |
|
Is / when will DECwindows be ICCCM compliant?
Vendors are asking...
|