DESIGN (xvobjects) functions


LIBRARY ROUTINE

xvw_getobject - get the object associated with a window

LIBRARY CALL

xvobject xvw_getobject(
   xvobject parent,
   Window   window,
   char     *wname)

INPUT

OUTPUT

none

RETURN VALUE

The sub-object is successful or NULL otherwise

DESCRIPTION

Retrieves a window from the screen as an xvobject so that the xvobject can then be used within an application that uses GUI & Visualization Services.

This routine can be used to allow the user to interactively select a window. The idea here is that the application programmer may want to request that the user "pick" a window, which then may be used as needed in the form of an xvobject. For this method of operation, pass the the wname as NULL, and the window as KNONE. The cursor will be changed to a cross, and events will be blocked until the user clicks the mouse on a window. That window will then be returned, in xvobject form, to the calling routine. Note that when this approach is used, it is best to precede the call to xvw_getobject() with a prompt about "Please choose a window", or it may appear to the user that the application is hung.

Alternatively, this routine can be used to take a window specified by its name, and translate it into an xvobject. For this method of operation, pass the window name as wname, and KNONE as the window ID. Being non-interactive, this method is better suited for obtaining the xvobject representation of a window when the window itself is already known. Note that the name and ID of a window may be obtained using the X11 utility program, "xwininfo". For instance, the following is from the xwininfo program:

xwininfo: Window id: 0x1c0000d "xterm"

In order to convert the above window into an xvobject, you would call xvw_getobject() with the following arguments:

xvw_getobject(NULL, KNONE, "xterm"); - or - xvw_getobject(NULL, KNONE, "0x1c0000d");

Alternatively, this routine can be used to take a window specified by its actual ID, and translate it into an xvobject. For this method of operation, pass the window ID as window, and the parent and wname as NULL. The following is an example given the window ID, specified by "window":

xvw_getobject(NULL, window, NULL);

The parent object allows the programmer to constrain the area in which the user is allowed to interactively select the object. If the parent is NULL, then the area is constrainted to the rootwindow.

A window manager is an example of where xvw_getobject() might be useful. Part of the nature of a window manager is to be able to reverse engineer existing windows, since the user may actually start or switch window managers during their X session. So if this was not done then the user would not be able to move, resize, or iconify the existing toplevel windows. By reverse engineering the toplevel windows as xvobjects, the programmer would then have full access to the xvobject manipulation routines, found in the xvwidget library, which may prove useful in simplifying writing of such an application.

ADDITIONAL INFORMATION

none

EXAMPLES

none

SIDE EFFECTS

none

RESTRICTIONS

none

MODIFICATION

none

FILES

$DESIGN/objects/library/xvobjects/src/utilities.c

SEE ALSO

xvobjects(3)

COPYRIGHT

Copyright (C) 1993 - 1997, Khoral Research, Inc. ("KRI") All rights reserved.