@setfilename ../info/x11
@node X11 Primitives, Miscellaneous, Events, top
@chapter X11 Primitives

@menu
* X Resources::			X Resources
* X Objects::			Creating X-window objects
* Client Messages::		Sending client messages
* X Properties::		Getting/Setting X window properties
* X Cursor::			Manipulating the X Cursor
* Other X Stuff::		Other Stuff
@end menu

Various primitive X11 facilities are provided which we describe here.

@node X Resources, X Objects, X11 Primitives, X11 Primitives
@section X Resources
@cindex X resources

Epoch X Resources give the ability to work with raw ``X resources'', such 
as the X server's internal ID numbers for screens (X ``windows'').  
These numbers are too big to fit into the standard GNU Emacs number size, 
so they are made a special opaque type called an @dfn{X-resource}.
X-resources contain X-window id information (32 bit quantity), and a type, 
which is always an X window system atom.   When the type of an Epoch X 
Resources is a predefined value (such as "X-Atom"), then it is referred to by
that type, (e.g. X-atom resource).
Currently recognized types are @code{Arc}, @code{Atom},
@code{Bitmap}, @code{Cardinal}, @code{Cursor}, @code{Drawable},
@code{Font}, @code{Integer}, @code{Pixmap}, @code{Point},
@code{Rectangle}, @code{String}, @code{Window}, @code{WMHints},
@code{WM Size Hints} or @code{Resource} (untyped).

@defun epoch::intern-atom name
Interns the string @var{name} as an X-atom resource (as opposed to Elisp atom).
@var{name} should be a string.  X-atom resources are 32-bit numbers
that represent strings in the X window system. They are used for typing
information on X window data objects.
@end defun

@defun epoch::unintern-atom name
Converts the X-atom resource @var{name} to an Elisp string.  Note that the
atom is not removed from the server.
@end defun

@defun epoch::resourcep arg
Returns @code{t} if @var{arg} is an X resource, @code{nil} otherwise.

In addition, the primitive @code{equal} has been extended to accept 
X resources. Two resources are @code{equal} if their values are the same,
regardless of type.
@end defun

@defun epoch::string-to-resource string type
Converts an elisp @var{string} to an X resource (raw window id, for
example) of given @var{type}.  @var{string} is assumed to represent a 32-bit
numeric value in the C language numeric literal format.
@var{type} must be an X-atom resource.
@end defun

@defun epoch::resource-to-type resource
Returns an X resource whose type is @code{atom} and whose  value is the type
of the @var{resource}.
@end defun

@defun epoch::resource-to-string resource &optional base
Convert the id of the @var{resource} to a numeric string. Optional
@var{base} specifies the base for the conversion (may be 2..36 inclusive).
Note that no special notation is used to signify the base.
@end defun

@defun epoch::xid-of-screen &optional screen
Returns the X-window resource value for the @var{screen}
(default: current-screen).
@end defun

@defun epoch::set-resource-type resource type
Sets the type field of @var{resource} to the value of @var{type}. @var{type}
must be an X-atom resource. Returns @var{resource} if it was successfully
modified, nil otherwise.
@end defun

@node X Objects, Client Messages, X Resources, X11 Primitives
@section X Objects
@cindex X objects

Several types of X objects can be encapsulated into Elisp. Each
is stored in Epoch as its X-window resource ID, in an X-resource data
object. When a function claims that it returns the X-window object, this
should be taken to mean that it returns an X-resource with the resource ID
and type stored in it. These resources can be manipulated with various
functions, @pxref{X Resources}.

@defun epoch::get-font name
Loads the font into the server, and returns the X Resource associated with it,
or @code{nil}.
@end defun

@defun epoch::get-color color
Allocates a slot in the X server default colormap for the @var{color}.
Returns an X Resource of type Cardinal, which is the pixel value for the
@var{color}. @var{color} can be a color name, a vector of length 3
specifying the red, green, blue components, or an X Resource of type Cardinal.
If the last, it is simply returned (this is so that the function can be
called on any representation without generating an error).
@end defun

@defun epoch::free-color color
Releases the X server colormap slot corresponding to the @var{color}.
@var{color} must be an X Resource of type Cardinal. No checking is done to
verify that the color was allocated by Epoch, or is available for
release. Once released, the pixel value can be reused for a different
color, so that anything still displayed in the color may change at any
time (through the action of another X client, or Epoch).
@end defun

@defun epoch::make-bitmap width height byte-string
Creates a bitmap, and returns it. The @var{width} and @var{height}
should be positive integers, specifying the size of the bitmap. There is
no way to change the size once the bitmap has been created. The 
@var{byte-string} should be a string, which will be interpreted as an array 
of bytes, not characters per se. The format corresponds directly to the 
standard X11 bitmap format. Each row of the bitmap is in integral number of 
bytes, floor(@var{width}+7 / 8) long, and should consist of @var{height} rows.
@end defun

@defun epoch::free-bitmap bitmap
Releases a bitmap from the X server. The bitmap should @emph{not} be
used again, even indirectly (e.g., in a style).
@end defun

@node Client Messages, X Properties, X Objects, X11 Primitives
@subsection Client Messages
@cindex client messages

@defun epoch::send-client-message to &optional from data type format
Sends a client message of @var{type} with @var{data} to the destination
@var{to} using @var{format} and @var{data}. The parameters have the 
following meaning:

@table @var
@item to
A screen or an X Resource of type Window.  @xref{X11 Primitives} for
more information.

@item from
A screen or an X Resource of type Window that serves as the source of
the message.  This defaults to the current screen.

@item data
The message data may be @code{nil} if there is no data, integer, string, or
a list or vector of integers or X-resources.  If it is simply a string,
the first 20 characters are transmitted, and interpreted as 1, 2 or 4-byte
data on the other end according to the @var{format} parameter.  If @var{data}
is @code{nil}, @code{0}s are sent.

@item type
This is an X-atom (as opposed to an elisp atom) and can be created by
@code{intern-atom}.  Usually something which conveys the meaning of
the message, e.g., @code{WM_CHANGE_STATE}.

@item format
The data for a client message is always 20 bytes long.  The format
statement tells how to interpret this.  The value must be one of the
following:

@table @code
@item nil
The format defaults to a value appropriate for the data, as determined
by Epoch.

@item 8
for 20 1-byte data objects.

@item 16
for 10 2-byte objects.

@item 32
for 5 4-byte objects.
@end table
@end table

@example
;; Fake an iconify message
(setq xroot (car (query-tree))) ; get the root window
;; IconicState is 3
;; Send to the root window, from the current screen,
;; with data 3 of type WM_CHANGE_STATE.
(send-client-message xroot nil 3
  (intern-atom "WM_CHANGE_STATE"))
@end example

@end defun

@node X Properties, X Cursor, Client Messages, X11 Primitives
@subsection X Properties
@cindex X properties

@defun epoch::get-property name &optional screen
Returns the X-Property @var{name} on the @var{screen}. @var{screen} can be
an X-window resource. @var{name} can be an X-atom resource or a string. 
The property value is returned in the most (in Epoch's opinion) convenient 
form.

If the property is an array of items (e.g., the @i{count} return value
is more than 1) then it is returned as a list.  Strings are converted to
Elisp strings, integers into Elisp integers (with a possible loss of
precision, since Elisp integers are less than 32 bits), and other 32-bit
types into X-resources.  Strings are handled specially - if nulls are
found in the returned byte array, they are assumed to represent string
seperators, and that the property is an array of these null-seperated
substrings.

If there is a failure (bad screen, no property, bad type, etc.), then
@code{nil} is returned.

@end defun

@defun epoch::set-property name value &optional screen
Sets the X-property @var{name} to @var{value} on the X-window @var{screen}.
@var{screen} can be an X-window resource. @var{name} can be an X-Atom
resource or a string. @var{value} must be a string, an integer, 
an X-resource, or an vector or list of these types. If it is a vector 
or list, the types of all the sequence elements must be the same, and for 
X-resources the X-resource types must also be the same.
@end defun

@node X Cursor, Other X Stuff, X Properties, X11 Primitives
@subsection X Cursor
@cindex X cursor

@defun epoch::query-pointer &optional screen-or-xwin
Returns a list containing x-coordinate, y-coordinate (in pixels) and
state of mouse.  Uses current screen if no @var{screen} argument is
given.
@end defun

@defun epoch::warp-pointer x y &optional screen-or-xwin
Warps cursor to (@var{x},@var{y}) location (in pixels) on @var{screen} 
relative to the upper-left corner.  Uses current screen if no @var{screen}
argument is given.
@end defun

@defun epoch::query-mouse &optional screen
Returns a list containing x-coordinate, y-coordinate (in character
position) and state of mouse.  Uses current screen if no @var{screen}
argument is given.
@end defun

@defun epoch::warp-mouse x y &optional screen
Warps cursor to (@var{x},@var{y}) location (in character position) on
@var{screen}.  Uses current screen if no @var{screen} argument is given.
@end defun

@node Other X Stuff, ,X Cursor, X11 Primitives
@section Other X Stuff

@defun epoch::rebind-key keysym shiftmask string
Rebinds a raw X key on the fly.  Takes as arguments the @var{keysym} to
rebind, the @var{shiftmask} for the rebinding, and a @var{string} to
send when that key is depressed. @var{keysym} should be a string, naming the keysym. @var{shiftmask} should be one of the following:
@table @code
@item integer
This is a bit-mask, with a bit for every modifier, just like an X shift
state.
@item symbol
The symbol should be one of @code{'shift}, @code{'lock},
@code{'control}, @code{'meta}, @code{'mod1} ... @code{'mod5}.
@code{'meta} and @code{'mod1} are equivalent.
@item list
A list of symbols, indicating multiple modifiers.  Because of X, modifiers
must be keysyms, keyremappings, etc..
@end table

This function does not affect keybindings for other X clients, but does 
affect all Epoch screens.  
@end defun

@defun epoch::mod-to-shiftmask index
Input is an X modifier @var{index}, output a shiftmask that can be passed
to @code{epoch::rebind-key}. OBSOLETE.
@end defun

@defun epoch::query-tree &optional screen-or-xwin
Returns a list of the form @code{(root parent . children)} where all the
elements are X-window resources. @code{root} is the X root window,
@code{parent} is the X parent window of @var{screen-or-xwin}
(@code{nil} if @var{screen-or-xwin} is the X root window), and
@code{children} is a list of the X child windows of @var{screen-or-xwin}.
@end defun

@defun epoch::set-bell arg
If @var{arg} is @code{nil}, Epoch will use an audible bell. If
non-@code{nil}, then a visual bell will be used.
@end defun

@defvar epoch::bell-volume
Controls the X bell volume. If a number from -100 to 100, then the value
is used as the bell volume, otherwise it is ignored and 50 is used. Note
that on many systems, the hardware does not support different bell
volumes, and so this may not be effective.
@end defvar
