xop -
Low-level X-Windows operations
package require Xop
xop ?options? opName ?args?
- -displayof pathName
- Specifies that the display to perform operations on or retrieve data
from should be the display of pathName. The default value
is ``.'', Tk's root window.
- -colormap colormapID
- Specifies that the colormap to use for the operation (if any
is needed) should be given by colormapID. The default is
None.
- -screennumber screenNo
- Specifies the screen on which the operation will take place, if
a screen number is required. The default value is 0.
The xop command performs low-level X-Windows operations,
such as raising and lowering windows, and retrieving window
properties. Common options immediately follow the xop command.
These options always come in option-name/value pairs, and the option name
always starts with a ``-''; the operation name never does.
All commands pay attention to the -displayof option;
the others are ignored, except as stated below.
The first argument of xop after the options is a subcommand name;
it specifies a general class of operation to perform. Each subcommand name
is followed by arguments that determine exactly what operation is performed.
Valid subcommands are:
- access
- control access to the X server
- bell
- control/query the keyboard bell
- buffer
- manipulate/query cut buffers
- colormap
- set/query the server's installed colormaps
- drawable
- manipulate/query an X drawable
- event
- query/manipulate the event queue
- focus
- query/change the X focus
- font
- get font info
- keyboard
- manipulate/query the keyboard
- pointer
- manipulate/query the pointer (mouse)
- saveset
- manipulate the save set
- screensaver
- get/change screensaver settings
- server
- manipulate/query general server settings
- window
- manipulate/query a window
- wmprops
- get window-manager-related properties
The access subcommand is for changing access control for the
X server, and for getting access information. The access subcommand
may take the forms:
- access control enable
- Enable access control for the server
- access control disable
- Disable access control for the server, i.e. allow access to any host that
requests it.
- access hostlist add hostNameList
- Add the hosts named in hostNameList to the list of hosts
that are allowed to open a display on this X server.
(Not yet implemented.)
- access hostlist get
- Return the list of hosts that have access to the server.
(Not yet implemented.)
- access hostlist remove hostNameList
- Remove the hosts named in hostNameList from the list of hosts
that are allowed to open a display on this X server.
(Not yet implemented.)
The bell subcommand is for controlling and/or querying
the server's keyboard bell. The bell commands may be:
- bell ring ?volume?
- Ring the bell, at volume volume. volume is an integer,
and is the percentage of the loudest bell volume. (The default
volume is 100%.)
- bell duration ?time?
- With no arguments, this command returns the bell duration, in milliseconds,
expressed as an integer. The time argument, if present, sets the
bell duration. (time is an integer, giving the bell duration
in milliseconds; a value of -1 restores the default.)
- bell frequency ?freq?
- With no arguments, returns the bell frequency in Hertz.
If freq is given, it sets the bell frequency.
(freq must be an integer; a value of -1 restores
the default bell frequency.)
- bell volume ?volume?
- With no arguments, returns the maximum bell volume, expressed as
a percentage of the server's or hardware's maximum volume capability.
If volume is given, it sets the maximum bell volume.
(volume must be an integer; a value of -1 restores
the default maximum volume.)
The buffer subcommand is for manipulating and/or querying
the server's cut buffers. The buffer commands may be:
- buffer bufferNumber contents ?string?
- If string is present, set the contents of buffer bufferNumber
to string; otherwise, return the contents of the buffer.
- buffer bufferNumber rotate
- Rotate the cut buffers; buffer 0 moves to buffer bufferNumber mod 8,
buffer 1 goes to buffer (bufferNumber+1) mod 8, and so forth.
NOTE: buffer rotation won't work unless ALL eight buffers have had
something stored in them. Often, this is not the case.
The colormap subcommand is for installing and uninstalling
colormaps. The colormap subcommands may be:
- colormap install
- Installs the colormap given by the -colormap option.
- colormap uninstall
- Uninstalls the colormap given by the -colormap option.
The drawable subcommand is for querying a drawable's (window's
or pixmap's) properties. The drawable subcommands are:
- drawable drawableID geometry
- Returns the geometry (width and height) of the drawable
given by drawableID.
- drawable drawableID getimage imageName
- Puts the contents of the drawable given by drawableID
into photo image imageName. It uses the colormap given by
the -colormap option. (NOTE: photo image imageName must
already exist; it will not automatically be created.)
- drawable drawableID killclient
- Kills the client that created drawable.
The event subcommand is for generating events and querying
the event queue. The event subcommands are:
- event numpending
- Returns the number of events in the event queue.
- event send windowID eventType args
- Sends an event of type eventType to window windowID.
The additional arguments determine the exact contents of the
XEvent structure that is sent. (See the ``EVENT ARGUMENTS''
section for a complete description.)
The focus subcommand is for querying the server's event focus.
The focus subcommands are:
- focus ?focusInfo?
- If focusInfo is present, set the focus as specified;
otherwise, return information about the current focus.
focusInfo is a list consisting of two elements: a window
and the ``revert to'' indicator. (See the XGetInputFocus
man page for details.) The window may be either a window ID, or
None or PointerRoot. The ``revert to'' indicator
may be Parent, PointerRoot, or None.
The font subcommand is for setting and querying the server's
font information.
The font subcommands are:
- font listnames ?pattern?
- Returns a list of names of currently-loaded fonts that match
pattern. pattern is a glob-style pattern, and defaults
to ``*'', so that by default it matches all loaded fonts.
- font path ?fontPath?
- If fontPath is present, set the current font path to fontPath.
(fontPath is given as a Tcl list of directories.) If not,
the command returns the current font path.
The keyboard subcommand is for setting and querying
keyboard characteristics. The keyboard subcommands are:
- keyboard autorepeat ?on|off|default?
- Turn the global autorepeat mode on or off, or set it to its default,
or return the current mode.
- keyboard autorepeat map ?repeatMap?
- If repeatMap is present, turn autorepeat on/off for the
specified keys. (NOTE: this is only effective if the global
autorepeat mode is ``on''.) repeatMap is a list consisting
of keycode/Boolean pairs, i.e. a keycode followed by a Boolean
followed by another keycode and another Boolean, and so forth.
If repeatMap is not present, then the current autorepeat
map is returned.
- keyboard click ?volume?
- Sets or gets the keyclick volume. volume is a number between
-1 and 100. A value of -1 restores the default keyclick volume;
other numbers represent a percentage of the maximum keyclick
volume.
- keyboard coderange
- Returns a list containing two elements: the minimum and maximum
allowed keycodes on the specified server.
- keyboard leds ?ledMap?
- Sets or returns the state of the keyboard LEDs. The format for
ledMap is similar to that of repeatMap, described
above. Each LED is numbered 0 through 31, and its state is indicated
as a Boolean value.
- keyboard mapping ?keymap?
- If keymap is not present,
get the current keyboard mapping. This is returned as a list
of keycode/keySymList pairs, i.e. a list with an even number of
elements, consisting of a keycode number, followed by a list of
keysym names, followed by another keycode number, then another
list of keysym names, etc. The list of keysym names may include
empty strings, indicating that the given keycode doesn't map to
any keysym. By convention, the first name in the keysym list
contains the keysym for the unmodified key, while the second
element (if present) is the keysym for the shifted key. (There
may be more than two keysyms, but the meaning of the third and
later keysyms is server-dependent.) If keymap is present,
set the current keyboard mapping.
- keyboard state
- Returns the keyboard state, i.e. an indication of what keys
are pressed. The return value is a list of the keycodes
of the pressed keys.
The pointer subcommand is for setting and querying
pointer characteristics, and for performing some pointer
control functions.
(NOTE: this is not yet implemented.)
The pointer subcommands are:
- pointer acceleration ?accelValue?
- Sets or gets the current pointer (mouse) acceleration value.
accelValue is a non-negative floating-point number.
- pointer accelthresh ?accelThreshold?
- Sets or gets the acceleration threshold, i.e. the number of pixels
of movement above which pointer acceleration is applied.
accelThreshold is an integer.
- pointer grab eventList grabWindow ?-ownerevents boolean? ?-confineto confineWindow?
- Grabs the pointer, and sends all events in eventList to window
grabWindow. If the -ownerevents option is false, then
all generated events are reported to grabWindow; if it is true,
then the event is reported with respect to grabWindow. This is
described (albeit rather unclearly) on the XGrabPointer manual page.
(When I figure out what this really does, I'll describe it here in detail.)
The -confineto
option specifies a window that the pointer should be confined to.
If unspecified, the pointer is not confined to any window.
- pointer grabbutton button eventList grabWindow ?options?
- Grabs the pointer button described by button,
and sends all events in eventList to window grabWindow.
button may be 1, 2, 3, 4, 5, or Any.
The options may be -ownerevents and -confineto, which behave as
described for the pointer grab command, or they may be
-modifiers modList, where modList is a Tcl list containing
any of the symbols Shift, Lock, Control, Mod1
through Mod5, or Any. The default value for modList is
the empty list, meaning that the button will be grabbed only if no
modifier keys are pressed.
- pointer mapping ?buttonMap?
- If buttonMap is not specified, returns the current pointer
button mapping. Otherwise sets it to buttonMap.
buttonMap consists of a list of integers; position in the
list indicates which physical button is mapped, while the number
in the list indicates what logical button X maps it to. (The default
mapping would be {1 2 3 4 5}.) A value of zero indicates that
the button should be disabled. The integers in the list must
not repeat. (NOTE: if you try to remap a button while it is pressed,
the mapping won't occur.)
- pointer position ?pos?
- Sets the current pointer position to pos, if specified;
otherwise, returns the current pointer position. pos is
a list of two integers.
- pointer state
- Returns the pointer button state. The return value is a list
of all the modifier keys and pointer buttons that are pressed.
The values in the list may be any of the constants Shift,
Lock, control, Mod1 through Mod5, and
Button1 through Button5.
- pointer ungrab
- Ungrab the pointer.
- pointer ungrabbutton button grabWindow ?-modifiers modList?
- Ungrab button for any grab on grabWindow with the
modifiers given by modList. modList is as given for
the grabbutton command, and defaults to Any;
The saveset subcommand is for manipulating the
server's save set. (See the X11 docs for a description
of the saveset.) The saveset subcommands are:
- saveset add windowID
- Add windowID to the saveset.
- saveset remove windowID
- Remove windowID from the saveset.
The screensaver subcommand is for setting and querying
the screensaver settings, and activating or resetting
the screensaver. The screensaver subcommands are:
- screensaver activate
- Activate the screensaver.
- screensaver blanking ?blankingPreference?
- Set/get the blanking behavior. blankingPreference may
be prefer, dontprefer, or default.
prefer indicates that the server should blank the screen
rather than invoke the screensaver; dontprefer indicates that
it should invoke the screensaver; default restores the
server's default behavior.
- screensaver exposures ?exposeBahavior?
- Sets/gets the behavior when the screensaver is deactivated.
exposeBahavior may be allow, dontallow, or
default. allow means that all windows that are visible
on the display should receive exposure events; dontallow
means that they should not. default restores the server's
default behavior.
- screensaver interval ?changeInterval?
- Set or get the screensaver change interval. This is the time
interval (in seconds) between periodic screensaver changes (if
supported by the server). A value of 0 indicates that no periodic
change should be made; a value of -1 restores the default interval.
- screensaver reset
- Reset (deactivate) the screensaver.
- screensaver timeout ?time?
- Set or get the screensaver timeout (in seconds).
A value of 0 disables the screen saver, while a value of
-1 restores the default timeout.
The server subcommand is for manipulating and querying
general server settings. The server subcommands are:
- server extensions
- Return a list of supported server extensions.
- server grab
- Grab the server.
- server ungrab
- Ungrab the server.
- server vendor
- Return the server's vendor string.
- server vendorrelese
- Return the server's vendor release string, i.e. the
server software's version number.
The window subcommand is for manipulating and querying
windows. The window subcommands are:
- window windowID attributes
- Get the attributes of windowID. This information is returned as
a list of name/value pairs (like the ``array set'' format).
- window windowID children
- Return a list of the X window IDs of the children of windowID.
- window windowID circulate subwindows direction
- Circulate the subwindows of windowID; direction may
be up or down.
- window windowID destroy
- Destroy windowID.
- window windowID destroysubwindows
- Destroy all subwindows of windowID.
- window windowID inthisapp
- Return 1 if windowID corresponds to a window in the current
application, 0 if not. (We could use winfo pathname to do this,
but Tk keeps some hidden windows that don't have an associated
widget path.)
- window windowID lower
- Lower windowID in the stacking order.
- window windowID map
- Map windowID.
- window windowID map&raise
- Map and raise windowID.
- window windowID mapsubwindows
- Map all subwindows of windowID.
- window windowID move x y
- Mobe windowID to position (x,y).
- window windowID move&resize x y w h
- Move windowID to position (x,y) and change
its width and height to w and h respectively.
- window windowID parent
- Return the X window ID of the parent of windowID.
- window windowID property change propName args
- Change property propName on window windowID.
(Not yet implemented.)
- window windowID property delete propName
- Delete property propName from windowID.
- window windowID raise
- Raise windowID.
- window windowID resize w h
- Resize windowID so that its width is w and its
height is h.
- window windowID unmap
- Unmap windowID.
The wmprops subcommand is for retrieving window-anager-related
properties from a window. The wmprops subcommands are:
- wmprops windowID clientmachine
- Returns the value of the window's XA_WM_CLIENT_MACHINE property.
- wmprops windowID colormapwindows
- Returns a list of window IDs. These are the IDs contained
in the WM_COLORMAPWINDOWS property.
- wmprops windowID hints
- Returns a list of window manager hints. These take the form of alternating
property names and values, as used, e.g., by the array set
command. Valid hint names are inputWM, initState,
iconWindowId, iconPixmapId, iconPosition,
iconMaskId, and groupWindowId. inputWM can be either 0 or 1;
initState can be DontCare, Normal, Zoom,
Iconic, or Inactive. iconWindowId and groupWindowId
are X window IDs, written as hexadecimal numbers, while iconPixmapId
and iconMaskId are hexadecimal pixmap IDs. iconPosition is
a list of two integers.
- wmprops windowID iconname
- Returns the desired icon name for windowID, i.e.
the value of the window's XA_WM_ICON_NAME property.
- wmprops windowID name
- Returns the window's name, i.e. the value of the XA_WM_NAME property.
(This is the string that should be used as a title if the
window manager makes decorations for the window.)
- wmprops windowID normalhints
- This command returns the ``normal hints'' for the specified
window, i.e. the standard properties that the application
specifies for the window. (These are used to indicate
desired layout information to the window manager.)
These properties are returned as a list of alternating
property names and values; this can be used in an array set
command to set the contents of a Tcl array. The array values
returned are userPosition, userSize, progPosition,
progSize, minSize, maxSize, resizeInc,
minAspect, maxAspect, baseSize, and
winGravity.
- wmprops windowID protocols
- This returns the values stored in the WM_PROTOCOLS property.
The values are returned as the strings WM_TAKE_FOCUS,
WM_SAVE_YOURSELF, and WM_DELETE_WINDOW.
- wmprops windowID sizehints
- This returns the value of the XA_WM_SIZE_HINTS property, which indicates
what size the application would like the window to have.
Several xop subcommands return multiple window characteristics;
these include the
window attributes
and
wmprops normalhints
commands. These characteristics are returned as sequences of name-value
pairs, as used by the array set command. For the
window attributes command, we have the following names and
values:
- position
- window position, returned as a list of two integers
- size
- window width/height, returned as a list of two integers
- borderwidth
- window border width in pixels (an integer)
- depth
- window depth, in bits
- root
- ID of root window on which this window lies
- class
- inputoutput or inputonly
- bitGravity
- forget, static, c (center), or one of the compass points
- winGravity
- unmap, static, c (center), or one of the compass points
- colormap
- The window's colormap ID
- mapInstalled
- 0 or 1, depending on whether or not this window's colormap is
currently installed in the server
- overrideRedirect
- 0 or 1, depending on whether or not the window overrides
substructure redirection
- mapState
- unmapped, unviewable, or viewable
For the wmprops normalhints command, we have names and values
as follows:
- userPosition
- User-requested position, as a list of two integers (column and row)
- userSize
- User-requested window size, as a list of two integers (width and height)
- progPosition
- Program-requested position, as a list of two integers (column and row)
- progSize
- Program-requested window size, as a list of two integers (width and height)
- minSize
- Minimum window size, as a list of two integers (width and height)
- maxSize
- Maximum window size, as a list of two integers (width and height)
- resizeInc
- Window resize increment, as a list of two integers
(width increment and height increment)
- minAspect
- Minimum aspect ratio, i.e. value of width/height. Returned as a list
of two integers, numerator/denominator.
- maxAspect
- Maximum aspect ratio, i.e. value of width/height. Returned as a list
of two integers, numerator/denominator.
- baseSize
- Use this instead of minSize, if it's set. This is the base
size with respect to which we measure size increments.
- winGravity
- Window gravity, i.e. which corner of the window to use as a reference
when positioning the window. Value is c (center) or one of the
compass points.
The xop send event command accepts, in addition to a window ID
and an event name, a list of option-value pairs that describes the
event that will be sent to the window. The event names are exactly
as used by the X library, including capitalization, e.g. it will
accept ButtonPress, KeyRelease, ClientMessage,
etc. This determines the type field in the XEvent structure
that will be sent to the window. The other fields are determined
by the option-value pairs that follow the event type. These pairs
are as follows:
- -above aboveWindow
- Specifies the "above" field in ConfigureNotify and
ConfigureRequest events. For either event type,
aboveWindow may be a windowID. For ConfigureRequest
events, it may also be the word above; for
ConfigureNotify events, it may also be the word none.
- -atom atomNumber
- This option specifies the atom field of the event. atomNumber
is an atom number, which can be obtained from the winfo atom command.
- -borderwidth width
- Specifies the border_width field. width is an integer.
- -button button
- Gives the button field of the event. button may be
any of the strings button1 through button5,
b1 through b5, the integers 1 through 5, or the strings
left, middle, or right. The strings may be either
upper or lower case, and left, middle, and right
may be abbreviated.
- -colormap colormapID
- Sets the event's colormap field. colormapID may
be any valid numeric colormap ID.
- -count count
- Specifies the count field. count may be any integer.
- -data data
- Gives the data field for the event. The format for data
is a list of integers. The number and allowed range of these integers
depends on the -format field. For a format of ``8'', you may
specify up to 20 integers in the range from 0 to 255. For a format
of ``16'', you are allowed up to 10 integers in the range 0 to 65,535.
For a format of ``32'', up to 5 integers are allowed, with no range
restrictions.
- -detail detail
- Specifies the detail field for ConfigureRequest,
EnterNotify, LeaveNotify, FocusIn,
and FocusOut events. For ConfigureRequest events,
detail may be none, above, below,
topif, bottomif, or opposite, in any case, with
any unambiguous abbreviation. For the other event types, detail
may be ancestor, inferior, nonlinear,
nonlinearvirtual, or virtual. Any abbreviation of
nonlinear will be accepted, as will any unambiguous
abbreviation, independent of case.
- -drawable drawableID
- Sets the drawable event field. drawableID may be any
valid drawable on the display.
- -event windowID
- Sets the event's event field. windowID may the ID of
any window on the display.
- -firstkey keyCode
- Specifies the first_keycode field for MappingNotify
events. keyCode is an integer.
- -focus boolean
- Sets the focus field of the event. This should be True
if the window is the focus window or one of its descendants,
and should be False otherwise.
- -format format
- Specifies the data format for ClientMessage events.
format may be 8, 16, or 32.
- -fromconfigure boolean
- Sets the from_configure field for UnmapNotify events.
- -height height
- Sets the event's height field. height may be any integer.
- -ishint boolean
- Specifies the is_hint field for MotionNotify events.
- -keycode keyCode
- Sets the keycode field. keyCode may be any integer.
- -keyvector keyCodeList
- Sets the key_vector field for KeymapNotify events.
keyCodeList is a Tcl list of integers.
- -majorcode int
- Specifies the major_code field in GraphicsExpose and
NoExpose events. This may be either an integer, or one of
the strings copyarea or copyplane, in upper or lower
case.
- -messagetype atomNumber
- Sets the message_type field in ClientMessage events.
atomNumber may be any integer.
- -minorcode int
- Specifies the minor_code field in GraphicsExpose and
NoExpose events. This may be any integer.
- -mode mode
- Sets the mode field in the event structure. mode may be
normal, grab, or ungrab, or any abbreviation
of them, in any case. These may also have ``notify'' prepended
to them, for consistency with Xlib.
- -new boolean
- Specifies the new field for ColormapNotify events.
- -overrideredirect boolean
- Specifies the override_redirect field for the event.
- -owner windowID
- Sets the owner field for the event.
- -parent windowID
- Sets the parent field for the event.
- -place place
- Specifies the place field for CirculateNotify and
CirculateRequest events. place may be
top or bottom, or any abbreviation of them.
- -property atomOrNone
- Sets the property field for SelectionNotify and
SelectionRequest events. atomOrNone may be either
an atom number or the word ``none''.
- -request req
- Specifies the request field for MappingNotify
events. req may be modifier, keyboard, or
pointer, or any abbreviation of them, in any case.
They may also be preceded by the prefix ``mapping'', for
consistency with Xlib.
- -requestor windowID
- Sets the requestor field of the event.
- -root windowID
- Sets the root field for the event.
- -samescreen boolean
- Sets the same_screen field for the event.
- -selection atomNumber
- Specifies the selection field for the event.
- -serial int
- Specifies the serial field of the event.
- -state state
- Sets the state field for the event. For ButtonPress
ButtonRelease, EnterNotify, LeaveNotify,
KeyPress, KeyRelease, and MotionNotify events,
state is a modifier mask, specified as a Tcl list
of modifier names. Valid modifier names are Shift,
Lock, Control, Mod1 through Mod5, and
Button1 through Button5. NOTE: these strings
must match exactly.
For ColormapNotify events, state may be installed
or fBuninstalled, or any abbreviation of them, in any case.
For PropertyNotify events, state may be newvalue
or delete, or any abbreviation of them.
For VisibilityNotify events, state may be fullyobscured,
partiallyobscured, or unobscured, or any abbreviation
of them.
- -subwindow windowID
- Sets the subwindow field.
- -target atomNumber
- Sets the target field for SelectionNotify and
SelectionRequest events.
- -time int
- Specifies the time field. time is an integer,
representing a time in milliseconds.
- -width width
- Sets the width field for the event. width is an integer.
- -window windowID
- Sets the window field for the event.
- -x xPos
- Sets the x field for the event. xPos may be any integer.
- -xroot xRootPos
- Sets the x_root field for the event. xRootPos may be any integer.
- -y yPos
- Sets the y field for the event. yPos may be any integer.
- -yroot yRootPos
- Sets the y_root field for the event. yRootPos may be any integer.
Specifying a field that does not exist in the specified event type
will cause an error. For more information on what the fields in
the event structures mean, see the Xlib documentation.
X11, Window operations