X11 Primitives
**************

Here we describe various primitive X11 facilities.

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 into a special opaque type called an X-resource.

X-resources contain X id information (a 32 bit quantity) and a type (an X atom).  When the type of an Epoch X Resource 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 Arc, Atom, Bitmap, Cardinal, Cursor, Drawable, Font, Integer, Pixmap, Point, Rectangle, String, Window, WMHints, WM Size Hints or Resource (untyped).

 -- Function: epoch::intern-atom name
     Interns the string NAME as an X-atom resource (as opposed to an Elisp atom).  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 data objects.

 -- Function: epoch::unintern-atom name
     Converts the X-atom Resource NAME into an Elisp string.  Note that the atom is not removed from the X server.

 -- Function: epoch::resourcep arg
     Returns t if ARG is an X resource, nil otherwise.

     In addition, the primitive equal has been extended to accept X resources.  Two resources are equal if their values are the same, regardless of type.

 -- Function: epoch::string-to-resource string type
     Converts an Elisp STRING to an X resource (raw window id, for example) of given TYPE.  STRING is assumed to represent a 32-bit numeric value in the C language numeric literal format. TYPE must be an X-atom resource.

 -- Function: epoch::resource-to-type resource
     Returns an X resource whose type is atom and whose value is the type of RESOURCE.

 -- Function: epoch::resource-to-string resource &optional base
     Convert the id of RESOURCE to a numeric string.  Optional BASE specifies the base for the conversion (may be 2 through 36 inclusive).  Note that no special notation is used to signify the base.

 -- Function: epoch::xid-of-screen &optional screen
     Returns the X resource value for SCREEN (default is the current screen).

 -- Function: epoch::set-resource-type resource type
     Sets the type field of RESOURCE to the value of TYPE. TYPE must be an X-atom resource.  Returns RESOURCE if it was successfully modified, nil otherwise.

X Objects
=========

Several types of X objects can be encapsulated into Elisp.  Each is stored in Epoch as its X resource ID, in an X-resource data object. When a function claims that it returns the X 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, see X Resources.

 -- Function: epoch::get-font name
     Loads the font into the server, and returns the X Resource associated with it, or nil if NAME isn't a valid font.

 -- Function: epoch::get-color color
     Allocates a slot in the X server default colormap for the COLOR. Returns an X Resource of type Cardinal, which is the pixel value for the COLOR.  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 the function can be called on any representation without generating an error).

 -- Function: epoch::free-color color
     Releases the X server colormap slot corresponding to the COLOR. 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).

 -- Function: epoch::color-components color
     Return a 3-vector containing the red, green and blue components of COLOR, which should be an X Resource of type Cardinal.

 -- Function: epoch::get-color-rw color
     Allocates a read-write color cell for COLOR.  Returns an X Resource of type Cardinal if successful; otherwise nil.

 -- Function: epoch::set-color-rw cell name
     Set read-write color cell CELL to NAME.  CELL must be an X Resource of type Cardinal; NAME may be a string, vector, or color name.

 -- Function: epoch::make-bitmap width height byte-string
     Creates a bitmap, and returns it.  The WIDTH and 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 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(WIDTH+7 / 8) long, and should consist of HEIGHT rows.

 -- Function: epoch::load-bitmap file
     Creates a bitmap, based on the information in FILE.  FILE should include the absolute pathname as well as filename of a standard X bitmap file.

 -- Function: epoch::free-bitmap bitmap
     Releases a bitmap from the X server.  The bitmap should not be used again, even indirectly (e.g., in a style).

Client Messages
---------------

 -- Function: epoch::send-client-message to &optional from data type format
     Sends a client message of TYPE with DATA to the destination TO using FORMAT and DATA. The parameters have the following meaning:

     to
          A screen or an X Resource of type Window.  See X11 Primitives for more information.

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

     data
          The message data may be 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 FORMAT parameter. If DATA is nil, 0s are sent.

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

     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:

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

          8
               for 20 1-byte data objects.

          16
               for 10 2-byte objects.

          32
               for 5 4-byte objects.

          ;; 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"))

X Properties
------------

 -- Function: epoch::get-property name &optional screen
     Returns the X-Property NAME on the SCREEN. SCREEN can be an X resource. 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 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 nil is returned.

 -- Function: epoch::set-property name value &optional screen
     Sets the X-property NAME to VALUE on the X SCREEN. SCREEN can be an X resource.  NAME can be an X-Atom resource or a string.  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.

X Selections
------------

 -- Function: epoch::get-selection-owner selection
     Returns an X Resource of type Window corresponding to the X11 client owning SELECTION.  SELECTION may be an X-Atom Resource or a string.  If SELECTION is not owned by any client, NIL is returned.

 -- Function: epoch::acquire-selection selection &optional screen
     Asserts ownership of SELECTION for the X SCREEN. SCREEN can be an X resource.  Uses current screen if no SCREEN is given.  If SCREEN is t, set SELECTION owner to None, and send Epoch a selection-clear event.

     Note that SELECTION's data should be stored in epoch::selection-alist so that Epoch can internally handle conversion requests and possible loss of ownership to other X11 clients.

 -- Function: epoch::convert-selection selection target property &optional screen
     Requests owner of SELECTION to convert selection's data to type TARGET and store result in PROPERTY.  Property will be hung on SCREEN, or current screen if no SCREEN argument is given. This function will wait internally for the selection value to be available, and will return this value if the selection is owned by a client and no timeout occurs waiting for the client response.

 -- Variable: epoch::selection-timeout 2
     This variable describes the amount of time (in seconds) for the epoch::convert-selection function to wait for a response before returning nil.  This pause will not occur in the event the selection is unowned.

 -- Variable: epoch::selection-alist
     This variable will hold an alist of (atom . value) for all selections owned by Epoch X windows.  It is the responsibility of the Elisp code under Epoch to store data in this alist upon asserting ownership of any selections.  When selection-clear events are processed, the corresponding entry is deleted from the alist.

     When selection-request events are processed internally, Epoch looks in this alist for selection data to be converted.  Currently, selection data must be of type String; the selection-notify event structure is set to None for invalid requests or requests of selections with null data.

 -- Variable: epoch::convert-selection-alist
     This variable will hold an alist of (atom function) for any user-supplied target atoms.  FUNCTION will be called with no arguments, and should return either a string or nil.

X Cursor
--------

 -- Function: 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 SCREEN argument is given.

 -- Function: epoch::warp-pointer x y &optional screen-or-xwin
     Warps cursor to (X,Y) location (in pixels) on SCREEN relative to the upper-left corner.  Uses current screen if no SCREEN argument is given.

 -- Function: epoch::ungrab-pointer
     Ungrabs the pointer.  This is useful after a mouse down event, so that another X client can act before the mouse up event.

 -- Function: 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 SCREEN argument is given.

 -- Function: epoch::warp-mouse x y &optional screen
     Warps cursor to (X,Y) location (in character position) on SCREEN.  Uses current screen if no SCREEN argument is given.

 -- Function: epoch::query-cursor &optional screen
     Returns a list (X . Y) corresponding to the cursor position in characters.  Uses current screen if no SCREEN argument is given.

 -- Function: epoch::query-cursor-pixels &optional screen
     Returns a list (X . Y) corresponding to the cursor position in pixels (Upperleft corner of cursor).  Uses current screen if no SCREEN argument is given.

Other X Stuff
=============

 -- Function: epoch::get-default name &optional class
     Does a lookup into X Resources database for NAME and CLASS (if specified).  Returns a string for the definition, or nil if lookup request failed.

 -- Function: epoch::rebind-key keysym shiftmask string
     Rebinds a raw X key.  Takes as arguments the KEYSYM to rebind, the SHIFTMASK for the rebinding, and a STRING to send when that key is pressed.  KEYSYM should be a string, naming the keysym. SHIFTMASK should be one of the following:

     integer
          This is a bit-mask, with a bit for every modifier, just like an X shift state.

     symbol
          The symbol should be one of 'shift, 'lock, 'control, 'meta, 'mod1 ... 'mod5. 'meta and 'mod1 are equivalent.

     list
          A list of symbols, indicating multiple modifiers.

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

 -- Function: epoch::mod-to-shiftmask index
     Input is an X modifier INDEX, output a shiftmask that can be passed to epoch::rebind-key.  This function is OBSOLETE.

 -- Function: epoch::query-tree &optional screen-or-xwin
     Returns a list of the form (root parent . children) where all the elements are X resources.  root is the X root window, parent is the X parent window of SCREEN-OR-XWIN (nil if SCREEN-OR-XWIN is the X root window), and children is a list of the X child windows of SCREEN-OR-XWIN.

 -- Function: epoch::set-bell arg
     If ARG is nil, Epoch will use an audible bell. If non-nil, then a visual bell will be used.

 -- Variable: 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.