\input texinfo  @c -*-texinfo-*-
@c
@c Era 0.88
@c
@c Marginal annotation information is out of date.
@c
@c $Revision: 1.2 $
@c $Date: 1993/12/21 22:32:01 $
@c $Author: jwz $
@c
@c %**start of header (This is for running Texinfo on a region.)
@setfilename ../info/era.info
@settitle Era 0.88
@c %**end of header (This is for running Texinfo on a region.)

@iftex
@finalout
@end iftex

@ifinfo
This file documents Era 0.88, the latest greatest implementation of GNU
Emacs.

@end ifinfo

@setchapternewpage odd
@titlepage
@sp 11
@center @titlefont{Era}
@sp 2
@center GNU Emacs for the X Windowing System
@sp 2
@center Version 0.88
@sp 2
@center Currently based on Lucid Emacs 19.8
@sp 2
@center October 1993

@page
@vskip 0pt plus 1filll
This is the current working documentation for Era.  All functionality
which has been added should be described somewhere herein.  There are
also notes about current problems and additional items scheduled to be
added in the future.  Most of this manual has been written by Ben Wing
and Chuck Thompson.  Jon Reid wrote the chapter on I18N Level 3.  Please
send all comments and suggestions to @code{bwing@@eng.sun.com} or
@code{cthomp@@cs.uiuc.edu}.
@end titlepage

@node top, Summary of New Features, (dir), (dir)
@ifinfo
The Era Editor
@end ifinfo

@menu
* Summary of New Features::
* Annotations::
* Internationalization::
* Partial Files::
* Emacs Client Widget::
* Atomic Extents::
* Disabling the Menu::
* Motif Drag and Drop::
* Xt Interface Functions::
* Improved Pixmap Support::
* ToolTalk Support::
* Miscellaneous (for now)::
@end menu

@node Summary of New Features, Annotations, top, top
@chapter Summary of New Features

@itemize @bullet
@item
Marginal and in-text annotations.

@item
Support for partial files.

@item
The ability to make Era a client widget.

@item
There is a new extent property, @code{'atomic}, which prevents point
from being positioned anywhere within the extent.

@item
It is possible to disable the menu; this is primarily for use in an
Emacs client widget.

@item
Support for drag-and-drop under Motif.  This support is general, and
all features accessible from C are also accessible from E-Lisp.

@item
Support for interfacing with Xt widgets.

@item
Support for interacting with ToolTalk.

@end itemize


@node Annotations, Internationalization, Summary of New Features, top
@chapter Annotations

@menu
* Annotation Basics::
* Annotation Primitives::
* Margin Primitives::
* Hooks::
@end menu


@node Annotation Basics, Annotation Primitives, Annotations, Annotations
@section Annotation Basics

Marginal annotations are notes associated with a particular location in
a buffer.  They may be displayed in a margin created on the left-hand
side of the screen, in any whitespace at the beginning of a line, or
inside of the text itself.  Every annotation may have an associated
action to be performed when the annotation is selected.  The term
@emph{annotation} is used to refer to an individual note.  The term
@emph{margin} is generically used to refer to the whitespace before the
first character on a line.

@table @code
@item annotation
Each annotation has the following characteristics:
@table @var
@item glyph
This may be either a bitmap/pixmap object or a string.
@item face
The face with which to display the glyph.
@item action
If non-nil this field must contain a function capable of being the
first argument to @code{funcall}.  This function is evaluated with a
single argument, the value of the @var{data} field, each time the
annotation is selected.
@item data
Not used internally.  This field can contain any Elisp object.  It is
passed as the lone argument to @var{action} described above.
@item type
Valid types are: @code{bitmap}, @code{pixmap} and @code{string}.
@end table
@end table


The margin is divided into @emph{outside} and @emph{inside}.  The
outside margin is space on the left side of the screen which normal text
cannot be displayed in.  The inside margin is that space between the
leftmost point text can be displayed and where the first character
actually is.

There are four different @emph{layout types} which affect the exact
location an annotation appears.

@table @code
@item outside-margin
The annotation is placed, left-justified, into the outside margin area.
If the outside margin is not wide enough for an annotation to fit it is
not displayed.

@item inside-margin
The annotation is placed, left-justified, into the inside margin area.
If the inside margin is not wide enough for the annotation to fit it
will be displayed using any available outside margin space if and only
if the variable @code{use-left-overflow} is non-@code{nil}.

@item whitespace
The annotation is placed, right-justified, into the inside margin area.
This puts the annotation as close as possible to the first
non-whitespace character on a line.  If the inside margin is not wide
enough for the annotation to fit it will be displayed if and only if the
variable @code{use-left-overflow} is non-@code{nil}.

@item text
The annotation is placed at the position it is inserted.  It will create
enough space for itself inside of the text area.  It does not take up a
place in the logical buffer, only in the display of the buffer.
@end table

The current layout policy is that all @code{whitespace} annotations are
displayed first.  Next, all @code{inside-margin} annotations are
displayed using any remaining space.  Finally as many
@code{outside-margin} annotations are displayed as possible.  The
@code{text} annotations will always display as they create their own
space to display in.


@node Annotation Primitives, Margin Primitives, Annotation Basics, Annotations
@section Annotation Primitives

@defun make-annotation glyph &optional position layout buffer
Create a marginal annotation with @var{glyph}, which may be a
bitmap/pixmap or a string at position @var{pos}.  Use layout policy
@var{layout} and place the annotation in buffer @var{buffer}.  If
@var{pos} is @code{nil}, point is used.  If @var{layout} is @code{nil},
@code{whitespace} is used.  If @var{buffer} is @code{nil}, the current
buffer is used.  Returns the newly create annotation.
@end defun

@defun delete-annotation annotation
Remove @var{annotation} from its buffer.  This does not modify the
buffer text.  Returns the annotation deleted.
@end defun

@defun annotationp annotation
Return @code{t} if @var{annotation} is an annotation, @code{nil}
otherwise.
@end defun

@defun annotation-visible annotation
Return @code{t} if there is enough available space to display
@var{annotation}, @code{nil} otherwise.
@end defun

@defun annotation-at &optional position buffer
Return the annotation at @var{position} in @var{buffer}.  If
@var{position} is @code{nil} point is used.  If @var{buffer} is
@code{nil} the current buffer is used.
@end defun

@defun annotation-layout annotation
Return the layout policy of @var{annotation}.
@end defun

@defun set-annotation-layout annotation layout
Set the layout policy of @var{annotation} to @var{layout}.
@end defun

@defun annotation-type annotation
Returns the display type of @var{annotation}.  The type will be one of
following symbols:
@table @code
@item
pixmap
@item
bitmap
@item
string
@item
nil (object is not an annotation)
@end table
@end defun

@defun annotation-width annotation
Return the width of @var{annotation} in pixels.
@end defun

@defun annotation-glyph annotation
If @var{annotation} is of type @code{string} return the string.
Otherwise return the bitmap or pixmap object of the glyph representing
@var{annotation}.
@end defun

@defun set-annotation-glyph annotation glyph &optional layout
Set the glyph image of @var{annotation} to @var{glyph}.  If
@var{layout} is non-@code{nil} set the layout policy of @var{annotation}
to @var{layout}.  Returns the new value of @code{annotation-glyph}.
@end defun

@defun annotation-data annotation
Return the data associated with @var{annotation}.
@end defun

@defun set-annotation-data annotation data
Set the data field of @var{annotation} to @var{data}.  Returns
@var{data}.
@end defun

@defun annotation-action annotation
Return the action associated with @var{annotation}.
@end defun

@defun set-annotation-action annotation action
Set the action field of @var{annotation} to @var{action}.  Returns
@var{action}.
@end defun

@defun annotation-face annotation
Return the face associated with @var{annotation}.
@end defun
        
@defun set-annotation-face annotation face
Set the face associated with @var{annotation} to @var{face}.
@end defun

@defun annotations-in-region start end buffer
Return a list of all annotations in @var{buffer} which are between
@var{start} and @var{end} inclusively.
@end defun

@defun annotation-at &optional position buffer
Return a list of all annotations at @var{position} in @var{buffer}.  If
@var{position} is @code{nil} point is used.  If @var{buffer} is
@code{nil} the current buffer is used.
@end defun

@defun annotation-list &optional buffer
Returns a list of all annotations in @var{buffer}.  If @var{buffer}
is @code{nil}, the current buffer is used.
@end defun

@defun all-annotations
Returns a list of all annotations in all buffers in existence.
@end defun


@node Margin Primitives, Hooks, Annotation Primitives, Annotations
@section Margin Primitives

It is possible to set values for both a left and a right hand side
margin.  Only the left side has been implemented.  All margin settings
are buffer-local at the moment.

@defun set-buffer-left-margin-width width &optional buffer
Set the width, in characters, of the left outside margin of @var{buffer}
to @var{width}.  If @var{buffer} is @code{nil}, the current buffer is
used.  Returns the new width.
@end defun

@defun set-buffer-right-margin-width width &optional buffer
Set the width, in characters, of the right outside margin of
@var{buffer} to @var{width}.  If @var{buffer} is @code{nil}, the current
buffer is used.  Returns the new width.
@end defun

@defun buffer-left-margin-width &optional buffer
Return the width of the left outside margin, in characters, of
@var{buffer}.  If @var{buffer} is @code{nil}, the current buffer is
used.
@end defun

@defun buffer-right-margin-width &optional buffer
Return the width of the right outside margin, in characters, of
@var{buffer}.  If @var{buffer} is @code{nil}, the current buffer is
used.
@end defun

@defun buffer-left-margin-pixwidth &optional buffer
Return the width of the left outside margin, in pixels, of @var{buffer}.
If @var{buffer} is @code{nil}, the current buffer is used.
@end defun

@defun buffer-right-margin-pixwidth &optional buffer
Return the width of the right outside margin, in pixels, of
@var{buffer}.  If @var{buffer} is @code{nil}, the current buffer is
used.
@end defun

@defvar use-left-overflow
If non-@code{nil} use the left outside margin as extra whitespace when
displaying @code{whitespace} and @code{inside-margin} annotations.
Defaults to @code{nil}.
@end defvar

The margin colors are controlled by the faces @code{left-margin} and
@code{right-margin}.  These can be set using the X resources
@code{Emacs*left-margin*background} and
@code{Emacs*left-margin*foreground}.  Likewise for the right margin.


@node Hooks,  , Margin Primitives, Annotations
@section Hooks

The following three hooks are provided for use with the marginal annotations:

@table @asis
@item @strong{@code{before-delete-annotation-hook}}
This hook is called immediately before an annotation is destroyed.  It
is passed a single argument, the annotation being destroyed.

@item @strong{@code{after-delete-annotation-hook}}
This hook is called immediately after an annotation is destroyed.  It
may contain any number of functions to run.  No arguments are passed to
any of the functions on the hook.

@item @strong{@code{make-annotation-hook}}
This hook is called immediately after an annotation is created.  It is
passed a single argument, the newly created annotation.

@end table


@node Internationalization, Partial Files, Annotations, top
@chapter Internationalization

@menu
* I18N Levels 1 and 2::
* I18N Level 3::
* I18N Level 4::
@end menu


@node I18N Levels 1 and 2, I18N Level 3, Internationalization, Internationalization
@section I18N Levels 1 and 2

Era is now compliant with I18N levels 1 and 2.  Specifically, this means
that it is 8-bit clean and correctly handles time and date functions.  Era
will correctly display the entire ISO-Latin 1 character set.

The compose key may now be used to create any character in the ISO-Latin 1
character set not directly available via the keyboard..  In order for the
compose key to work it is necessary to load the file @file{x-compose.el}.
At any time while composing a character, @code{C-h} will display all valid
completions and the character which would be produced.


@node I18N Level 3, I18N Level 4, I18N Levels 1 and 2, Internationalization
@section I18N Level 3

@menu
* Level 3 Basics::
* Level 3 Primitives::
* Dynamic Messaging::
* Domain Specification::
* Documentation String Extraction::
@end menu

@node Level 3 Basics, Level 3 Primitives, I18N Level 3, I18N Level 3
@subsection Level 3 Basics

Era now provides alpha-level functionality for I18N Level 3.  This means
that everything necessary for full messaging is available, but not every
file has been converted.

The two message files which have been created are @file{src/emacs.po} and
@file{lisp/packages/mh-e.po}.  Both files need to be converted using
@code{msgfmt}, and the resulting @file{.mo} files placed in some locale's
@code{LC_MESSAGES} directory.  The test ``translations'' in these files are
the original messages prefixed by @code{TRNSLT_}.

The domain for a variable is stored on the variable's property list under
the property name @var{variable-domain}.  The function
@code{documentation-property} uses this information when translating a
variable's documentation.


@node Level 3 Primitives, Dynamic Messaging, Level 3 Basics, I18N Level 3
@subsection Level 3 Primitives

@defun gettext string
This function looks up @var{string} in the default message domain and
returns its translation.  If @code{I18N3} was not enabled when Era was
compiled, it just returns @var{string}.
@end defun

@defun dgettext domain string
This function looks up @var{string} in the specified message domain and
returns its translation.  If @code{I18N3} was not enabled when Era was
compiled, it just returns @var{string}.
@end defun

@defun bind-text-domain domain pathname
This function associates a pathname with a message domain.
Here's how the path to message file is constructed under SunOS 5.x:

@example
@code{@{pathname@}/@{LANG@}/LC_MESSAGES/@{domain@}.mo}
@end example

If @code{I18N3} was not enabled when Era was compiled, this function does
nothing.
@end defun

@defspec domain string
This function specifies the text domain used for translating documentation
strings and interactive prompts of a function.  For example, write:

@example
(defun foo (arg) "Doc string" (domain "emacs-foo") @dots{})
@end example

to specify @code{emacs-foo} as the text domain of the function @code{foo}.
The ``call'' to @code{domain} is actually a declaration rather than a
function; when actually called, @code{domain} just returns @code{nil}
@end defspec

@defun domain-of function
This function returns the text domain of @var{function}; it returns
@code{nil} if it is the default domain.  If @code{I18N3} was not enabled
when Era was compiled, it always returns @code{nil}.
@end defun


@node Dynamic Messaging, Domain Specification, Level 3 Primitives, I18N Level 3
@subsection Dynamic Messaging

The @code{format} function has been extended to permit you to change the
order of parameter insertion.  For example, the conversion format
@code{%1$s} inserts parameter one as a string, while @code{%2$s} inserts
parameter two.  This is useful when creating translations which require you
to change the word order.


@node Domain Specification, Documentation String Extraction, Dynamic Messaging, I18N Level 3
@subsection Domain Specification

The default message domain of Era is `emacs'.  For add-on packages, it is
best to use a different domain.  For example, let us say we want to convert
the ``gorilla'' package to use the domain `emacs-gorilla'.
To translate the message ``What gorilla?'', use @code{dgettext} as follows:

@example
(dgettext "emacs-gorilla" "What gorilla?")
@end example

A function (or macro) which has a documentation string or an interactive
prompt needs to be associated with the domain in order for the documentation
or prompt to be translated.  This is done with the @code{domain} special
form as follows:

@page
@example
(defun scratch (location)
  "Scratch the specified location."
  (domain "emacs-gorilla")
  (interactive "sScratch: ")
  @dots{} )
@end example

It is most efficient to specify the domain in the first line of of the
function body, before the @code{interactive} form.

For variables and constants which have documentation strings, specify the
domain after the documentation.

@defspec defvar symbol [value [doc-string [domain]]]
Example:
@example
(defvar weight 250 "Weight of gorilla, in pounds." "emacs-gorilla")
@end example
@end defspec

@defspec defconst symbol [value [doc-string [domain]]]
Example:
@example
(defconst limbs 4 "Number of limbs" "emacs-gorilla")
@end example
@end defspec

Autoloaded functions which are specified in @file{loaddefs.el} do not need
to have a domain specification, because their documentation strings are
extracted into the main message base.  However, for autoloaded functions
which are specified in a separate package, use following syntax:

@defun autoload symbol filename &optional docstring interactive macro domain
Example:
@example
(autoload 'explore "jungle" "Explore the jungle." nil nil "emacs-gorilla")
@end example
@end defun


@node Documentation String Extraction,  , Domain Specification, I18N Level 3
@subsection Documentation String Extraction

The utility @file{etc/make-po} scans the file @code{DOC} to extract
documentation strings and creates a message file @code{doc.po}.  This file
may then be inserted within @code{emacs.po}.

Currently, @code{make-po} is hard-coded to read from @code{DOC} and write
to @code{doc.po}.  In order to extract documentation strings from an add-on
package, first run @code{make-docfile} on the package to produce the
@code{DOC} file.  Then run @code{make-po -p} with the @code{-p} argument to
indicate that we are extracting documentation for an add-on package.

(The @code{-p} argument is a kludge to make up for a subtle difference
between pre-loaded documentation and add-on documentation:  For add-on
packages, the final carriage returns in the strings produced by
@code{make-docfile} must be ignored.)

@node I18N Level 4,  , I18N Level 3, Internationalization
@section I18N Level 4

Not yet documented.


@node Partial Files, Emacs Client Widget, Internationalization, top
@chapter Partial Files

@menu
* Intro to Partial Files::
* Creating a Partial File::
* Detached Partial Files::
@end menu


@node Intro to Partial Files, Creating a Partial File, Partial Files, Partial Files
@section Intro to Partial Files

Partial files are now supported.  A @dfn{partial file} is a section of a
buffer (called the @dfn{master buffer}) that is placed in its own buffer
and treated as its own file.  Changes made to the partial file are not
reflected in the master buffer until the partial file is ``saved'' using
the standard buffer save commands.  Partial files can be ``reverted''
(from the master buffer) just like normal files.  When a file part is
active on a master buffer, that section of the master buffer is marked
as read-only.  Two file parts on the same master buffer are not allowed
to overlap.  Partial file buffers are indicated by the words @samp{File
Part} in the modeline.

The master buffer knows about all the partial files that are active on
it, and thus killing or reverting the master buffer will be handled
properly.  When the master buffer is saved, if there are any unsaved
partial files active on it then the user will be given the opportunity
to first save these files.

When a partial file buffer is first modified, the master buffer is
automatically marked as modified so that saving the master buffer will
work correctly.


@node Creating a Partial File, Detached Partial Files, Intro to Partial Files, Partial Files
@section Creating a Partial File

@defun make-file-part &optional start end name buffer
Make a file part on buffer @var{buffer} out of the region.  Call it
@var{name}.  This command creates a new buffer containing the contents
of the region and marks the buffer as referring to the specified buffer,
called the @dfn{master buffer}.  When the file-part buffer is saved, its
changes are integrated back into the master buffer.  When the master
buffer is deleted, all file parts are deleted with it.

When called from a function, expects four arguments, @var{start},
@var{end}, @var{name}, and @var{buffer}, all of which are optional and
default to the beginning of @var{buffer}, the end of @var{buffer}, a
name generated from @var{buffer} name, and the current buffer,
respectively.
@end defun


@node Detached Partial Files,  , Creating a Partial File, Partial Files
@section Detached Partial Files

Every partial file has an extent in the master buffer associated with it
(called the @dfn{master extent}), marking where in the master buffer the
partial file begins and ends.  If the text in master buffer that is
contained by the extent is deleted, then the extent becomes
``detached'', meaning that it no longer refers to a specific region of
the master buffer.  This can happen either when the text is deleted
directly or when the master buffer is reverted.  Neither of these should
happen in normal usage because the master buffer should generally not be
edited directly.

Before doing any operation that references a partial file's master
extent, Emacs checks to make sure that the extent is not detached.  If
this is the case, Emacs warns the user of this and the master extent is
deleted out of the master buffer, disconnecting the file part.  The file
part's filename is cleared and thus must be explicitly specified if the
detached file part is to be saved.


@node Emacs Client Widget, Atomic Extents, Partial Files, top
@chapter Emacs Client Widget

An @dfn{Emacs client widget} is a widget that is part of another program
but functions as an Emacs screen.  This is intended to be a more
powerful replacement for standard text widgets.

@menu
* Using an Emacs Client Widget::
* Emacs Client Widget Resource Settings::
* Motif-Specific Info About the Emacs Client Widget::
@end menu


@node Using an Emacs Client Widget, Emacs Client Widget Resource Settings, Emacs Client Widget, Emacs Client Widget
@section Using an Emacs Client Widget

The current implementation of the Emacs client widget is designed for
use in a Motif application; thus it is a subclass of the base Motif
widget XmPrimitive.  In order to use an Emacs client widget in a client
program, simply create an instance of widget type EmacsClient and link
your program with the library libemacsclient.a or libemacsclient.so.
The corresponding header file is called @file{EmacsWidget.h}.  (There
was already a file called @file{emacsclient.c} elsewhere in Emacs.)

The Emacs client widget will not do anything until an instance of Emacs
is told about this particular widget.  To do that, call the function
@code{x-create-screen}, passing as its second argument a string
containing the decimal representation of the widget's X window ID number
(this can be obtained by the Xt function @code{XtWindow()}).  In order
for the client program to communicate this information to Emacs, a
method such as sending a ToolTalk message needs to be used.

Once @code{x-create-screen} has been called, Emacs will create a screen
that occupies the client widget's window.  This screen can be used just
like any other screen in Emacs.


@node Emacs Client Widget Resource Settings, Motif-Specific Info About the Emacs Client Widget, Using an Emacs Client Widget, Emacs Client Widget
@section Emacs Client Widget Resource Settings

The Emacs client widget is a subclass of the Motif widget XmPrimitive
and thus inherits all its resources.  In addition, the following new
resources are defined:

@table @samp
@item deadShell (class DeadShell)
A boolean resource indicating whether the last request to the
EmacsShell widget that contains the screen corresponding to this
widget timed out.  If true, no further requests will be made (all
requests will automatically fail) until a response to the last
request is received.  This resource should normally not be set by the
user.

@item shellTimeout (class ShellTimeout)
A value specifying how long (in milliseconds) the client should wait
for a response when making a request to the corresponding EmacsShell
widget.  If this timeout is exceeded, the client will assume that the
shell is dead and will fail the request and all subsequent requests
until a response to the request is received.  Default value is 5000,
or 5 seconds.
@end table

The shell that contains the screen corresponding to an Emacs client
widget is of type EmacsShell, as opposed to standard screens, whose
shell is of type TopLevelShell.  The EmacsShell widget is a direct
subclass of Shell and thus inherits its resources.  In addition, the
following new resources are defined:

@table @samp
@item window (class Window)
The X window ID of the widget to use for this Emacs screen.  This is
normally set by the call to @code{x-create-screen} and should not be
modified by the user.

@item deadClient (class DeadClient)
A boolean resource indicating whether the last request to the
corresponding EmacsClient widget timed out.  If true, no further
requests will be made (all requests will automatically fail) until a
response to the last request is received.  This resource should
normally not be set by the user.

@item ClientTimeout (class ClientTimeout)
A value specifying how long (in milliseconds) the shell should wait
for a response when making a request to the corresponding EmacsClient
widget.  If this timeout is exceeded, the shell will assume that the
client is dead and will fail the request and all subsequent requests
until a response to the request is received.  Default value is 5000,
or 5 seconds.
@end table

Note that the requests that are made between the client and the shell
are primarily for handling query-geometry and geometry-manager requests
made by parent or child widgets.


@node Motif-Specific Info About the Emacs Client Widget,  , Emacs Client Widget Resource Settings, Emacs Client Widget
@section Motif-Specific Info About the Emacs Client Widget

By default, the Emacs client widget has navigation type
@samp{XmTAB_GROUP}.

The widget traversal keystrokes are modified slightly from the standard
XmPrimitive keystrokes.  In particular, @kbd{@key{TAB}} alone does not
traverse to the next widget (@kbd{Ctrl-@key{TAB}} must be used instead),
but functions like a normal @key{TAB} in Emacs.  This follows the
semantics of the Motif text widget.  The traversal keystrokes
@kbd{Ctrl-@key{TAB}} and @kbd{Shift-@key{TAB}} are silently filtered by
the Emacs client widget and are not seen by Emacs.


@node Atomic Extents, Disabling the Menu, Emacs Client Widget, top
@chapter Atomic Extents

There is a new extent attribute, @code{'atomic}, which can be set with
@code{set-extent-attribute}.  When an extent is marked as atomic, point
cannot be positioned anywhere within the extent by any cursor motion or
positioning commands.  Cursor motion commands such as
@code{forward-char}, @code{backward-char}, @code{scroll-up}, etc. will
skip over the extent and position point at the other end.  Attempts to
directly position point inside an atomic extent by using
@code{goto-char} or the mouse positioning commands will cause point to
be placed at whichever end of the extent is closer to the desired
position.

To turn off the atomic attribute of an extent, call
@code{set-extent-attribute} with attribute @code{'non-atomic}.


@node Disabling the Menu, Motif Drag and Drop, Atomic Extents, top
@chapter Disabling the Menu

There is a new boolean EmacsScreen resource, @code{nomenu}, which will
cause the screen's menubar not to appear if set to true.  This was
primarily implemented for Emacs client widgets.


@node Motif Drag and Drop, Xt Interface Functions, Disabling the Menu, top
@chapter Motif Drag and Drop

@menu
* Introduction to Drag and Drop::
* More About Drag and Drop::
* Programming Drag and Drop::
* Drag and Drop Functions::
* Drag and Drop Widgets::
* Drag and Drop Internal Information::
@end menu

@node Introduction to Drag and Drop, More About Drag and Drop, Motif Drag and Drop, Motif Drag and Drop
@section Introduction to Drag and Drop

@dfn{drag-and-drop} is a general facility for exchanging information
between applications or between sections of an application, and can also
be used for other purposes such as performing operations on data objects.
The paradigm involves dragging a visual representation of a data object
across the screen to a target (or @dfn{drop site}) and dropping it there.
The drop site can be a document that the object is to be included in,
an operation to be performed on the object, etc.  Three different general
operations, known as @dfn{copy}, @dfn{move}, and @dfn{link}, can be performed
on the data object when it is dropped on the target.  The actual operation
performed depends on the operations allowed by the drag source and drop
site and the keys held down by the user during the drag.  There is no set
definition of what it means, for example, to ``copy'' the object from one
place to another; the semantics of these three operations are left to the
individual applications involved.

@node More About Drag and Drop, Programming Drag and Drop, Introduction to Drag and Drop, Motif Drag and Drop
@section More About Drag and Drop

Drag-and-drop, as implemented under Motif, is an extremely general and
heavily customizable facility.  In order to manage this flexibility without
excessive complexity, the Xt concept of @dfn{widgets}, which are objects
that encapsulate data and functions, is used heavily.  Consequently, Era
provides a direct interface to Xt widget manipulation functions
(@pxref{Xt Interface Functions}).

During the drag, @dfn{drag-over} and @dfn{drag-under} visuals take place.
The drag-over visual is the visual representation of the data being
dragged, and includes sections that indicate what operation will be
performed when the object is dropped and whether the object is currently
over a valid drop site.  The drag-over visual may change as the object
passes over different drop sites and non-drop-site areas.  The appearance
of the drag-over visual is determined by the drag-source application.

A drag-under visual is a change that happens to a drop site as the object
is dragged over the site.  This can include highlighting the drop site,
making it look pushed-in or popped-out, replacing it with a bitmap,
or possibly even doing complicated actions such as producing a sound and
animating a picture.  The drag-under visuals are determined by either
the drag-source application or drop-site application, depending on the
@dfn{protocol} used during the drag.

There are two possible protocols that can be used during the dragging.
The choice of protocol determines mostly whether the drop-site application
is involved in the drag and consequently the nature of the visuals
used during the drag.  In the @dfn{preregister} protocol, the drop-site
application is not involved at all during the drag.  It stores information
about valid drop sites and desired drag-under visuals in X properties
associated with the drop-site application's window(s), and the drag-source
application reads this and is entirely responsible for the drag-under
visuals.  In the @dfn{dynamic} protocol, the drag-source application
communicates with the drop-site application during the drag, and the
latter is responsible for drag-under visuals.  The dynamic protocol is
more flexible and allows for complex drag-under visuals, nested and
overlapping drop sites, etc., but imposes some other limitations and
uses more server resources.  The applications involved or the user can
specify which protocol is preferred and/or supported, and the Motif
toolkit determines from this information which protocol to use.  It
is possible that no protocol will satisfy both applications; in this
case, there are no drag-over or drag-under visuals.

When a drop occurs, information is exchanged using the X selection
protocol, which is a basic, general, low-level method for exchanging
data between applications.  Information exchanged through the
selection mechanism always comes in a particular format, known as a
@dfn{target} in drag-and-drop.  This format can be a string, a list
of integers, a bitmap in standard X format, etc.  The drag-source and
drop-site application each specify a list of targets that are supported
for exchanging data; there must be at least one target in common for
data to be exchanged.

@node Programming Drag and Drop, Drag and Drop Functions, More About Drag and Drop, Motif Drag and Drop
@section Programming Drag and Drop

@itemize @bullet
@item
Before the drag, the drop-site application registers information about
each drop site, including the location of the site, the operations and
targets supported, a callback function to be called when an object is
dropped on the site, the nature of the drag-under visuals to be used,
and optionally a callback function to be called as an object is dragged
over the site (this applies only in the dynamic protocol).

@item
When the user begins a drag, the drag-source application specifies
information about the object being dragged, including the operations and
targets supported, the nature of the drag-over visuals to be used, and
various callback functions.

@item
During the drag, callback functions in the drag-source and/or drop-site
application may be called as the object is dragged over different drop
sites, depending on the protocol being used and on whether any
appropriate callback functions have been registered.  Either these
callback functions or the Motif toolkit itself supplies the drag-over
and drag-under visuals.

@item
When the object is dropped, the appropriate callback function in the
drop-site application is called, and it determines whether a drop is
allowable and what the targets should be for exchanging the information.
The drop-start callback function in the drag-source application is also
called, if such a callback is defined.

@item
For each valid target, the transfer callback function in the drag-source
application is called to send the data, and the corresponding transfer
callback function in the drop-site application is called to receive the
data.

@item
When all targets have been processed, the drop-finish callback function
in the drag-source application is called, if such a callback is defined.
@end itemize

@node Drag and Drop Functions, Drag and Drop Widgets, Programming Drag and Drop, Motif Drag and Drop
@section Drag and Drop Functions

@defun xm-create-drag-icon screen name values
@end defun

@defun xm-drag-cancel
@end defun

@defun xm-drag-start
Initiate a drag-and-drop transaction.  Equivalent to @code{XmDragStart}
in C.  A drag-and-drop transaction is started on @var{screen} and a
widget of class @code{xm-drag-context} is returned, with its values
initialized from @var{values}, an alist of (@var{resource}
. @var{value}) pairs.  See @code{xt-set-values} (@pxref{Widget
Functions}).
@end defun

@defun xm-drop-site-configure-stacking-order
@end defun

@defun xm-drop-site-end-update
@end defun

@defun xm-drop-site-query-stacking-order
@end defun

@defun xm-drop-site-register
@end defun

@defun xm-drop-site-start-update
@end defun

@defun xm-drop-site-unregister
@end defun

@defun xm-drop-transfer-add
@end defun

@defun xm-drop-transfer-start
@end defun

@defun xm-get-drag-context
@end defun

@defun xm-get-xm-display
@end defun

@defun xm-get-xm-screen
@end defun

@defun xm-targets-are-compatible
@end defun

@node Drag and Drop Widgets, Drag and Drop Internal Information, Drag and Drop Functions, Motif Drag and Drop
@section Drag and Drop Widgets

At the beginning of the description of each resource, a list of properties is
given as follows:
@example
(type default-value access)
@end example

Only capsule summaries of the meanings of the widget resources and given.
For more information on these widgets and their associated resources, see
the book @cite{OSF/Motif Programmer's Reference}.

@menu
* xm-display::
* xm-screen::
* xm-drag-icon::
* xm-drag-context::
* xm-drop-site::
* xm-drop-transfer::
@end menu

@node xm-display, xm-screen, Drag and Drop Widgets, Drag and Drop Widgets
@subsection xm-display

This is equivalent to the C widget @code{XmDisplay}, specifying per-
display resources as follows:

@table @code
@item drag-initiator-protocol-style
Specifies the default virtual bindings for the display.
@item drag-initiator-protocol-style
Specifies the drag and drop protocol requirements or preference when
the client is an initiator.
@item drag-receiver-protocol-style
Specifies the drag and drop protocol requirements or preference when
this client is a receiver.
@end table

@node xm-screen, xm-drag-icon, xm-display, Drag and Drop Widgets
@subsection xm-screen

This is equivalent to the C widget @code{XmScreen}, specifying per-
screen resources as follows:

@table @code
@item dark-threshold
An integer between 0 (zero) and 100, inclusive, that specifies a level
of perceived brightness for a color.
@item default-copy-cursor-icon
Specifies the DragIcon used during a drag operation when the operation
is a copy and no other pixmap is specified by the application.
@item default-invalid-cursor-icon
Specifies the DragIcon used to indicate that the cursor is over an
invalid drop site during a drag operation when no other pixmap symbol is
specified by the application.
@item default-link-cursor-icon
Specifies the DragIcon used during a drag operation when the operation
is a link and no other pixmap is specified by the application.
@item default-move-cursor-icon
Specifies the DragIcon used during a drag operation when the operation
is a move and no other pixmap is specified by the application.
@item default-none-cursor-icon
Specifies the DragIcon used to indicate that the cursor is not over a
drop site during a drag operation when no other pixmap symbol is
specified by the application.
@item default-source-cursor-icon
Specifies the depth-1 pixmap used as a cursor when a
@code{source-cursor-icon} is not provided by the DragContext, or it is
not usable.
@item default-valid-cursor-icon
Specifies the DragIcon used to indicate that the cursor is over a valid
drop site during a drag operation when no other pixmap symbol is
specified by the application.
@item font
@item foreground-threshold
An integer between 0 (zero) and 100, inclusive, that specifies a level
of perceived brightness for a color.
@item horizontal-font-unit
@item light-threshold
An integer between 0 (zero) and 100, inclusive, that specifies a level
of perceived brightness for a color.
@item menu-cursor
@item move-opaque
@item unpost-behavior
@item vertical-font-unit
@end table

@node xm-drag-icon, xm-drag-context, xm-screen, Drag and Drop Widgets
@subsection xm-drag-icon

This is the equivalent of the C widget @code{XmDragIcon}, used to
represent the source data in a drag-and-drop transaction.  Resources are
as follows:

@table @code
@item attachment
Specifies a relative location on the source icon for the attachment of
the state or operation icon.
@item depth
@item height
@item hot-x
Specifies the x-coordinate of the hotspot of a cursor DragIcon in
relation to the origin of the pixmap bounding box.
@item hot-y
Specifies the y-coordinate of the hotspot of a cursor DragIcon in
relation to the origin of the pixmap bounding box.
@item mask
Specifies a pixmap of depth 1 to use as the DragIcon mask pixmap.
@item offset-x
Specifies a horizontal offset (in pixels) of the origin of the state or
operation icon relative to the attachment point on the source icon.
@item offset-y
Specifies a vertical offset (in pixels) of the origin of the state or
operation icon relative to the attachment point on the source icon.
@item pixmap
Specifies a pixmap to use as the DragIcon pixmap.
@item width
@end table

@node xm-drag-context, xm-drop-site, xm-drag-icon, Drag and Drop Widgets
@subsection xm-drag-context

This is the equivalent of the C widget @code{XmDragContext}, used to
hold information for and track the state of a drag-and-drop transaction.
Resources are as follows:

@table @code
@item blend-model
Specifies which combination of DragIcons are blended to produce a
drag-over visual.
@item client-data
Specifies the client data to be passed to @code{convert-proc} when it is
invoked.
@item convert-proc
Specifies a procedure of type !!!!!!!!!!!!!!!!!!! that converts the
source data to the format(s) requested by the receiver client.
@item cursor-background
Specifies the background pixel value of the cursor.
@item cursor-foreground
Specifies the foreground pixel value of the cursor when the state icon is not blended.
@item drag-drop-finish-callback
Specifies the list of callbacks that are called when the transaction is completed.
@item drag-motion-callback
Specifies the list of callbacks that are invoked when the pointer moves.
@item drop-operations
Specifies the set of valid operations associated with an initiator client for a drag transaction.
@item drop-finish-callback
Specifies the list of callbacks that are invoked when the drop is completed.
@item drop-site-enter-callback
Specifies the list of callbacks that are invoked when the pointer enters a drop site.
@item drop-site-leave-callback
Specifies the list of callbacks that are invoked when the pointer leaves a drop site.
@item drop-start-callback
Specifies the list of callbacks that are invoked when a drop is initiated.
@item export-targets
Specifies the list of target atoms associated with this source.
@item incremental
Specifies a Boolean value that indicates whether the transfer on the
initiator side uses the Xt incremental selection transfer mechanism
described in @cite{X Toolkit Intrinsics--C Language Interface}.
@item invalid-cursor-foreground
Specifies the foreground pixel value of the cursor when the state is invalid.
@item none-cursor-foreground
Specifies the foreground pixel value of the cursor when the state is none.
@item num-export-targets
@item operation-changed-callback
Specifies the list of callbacks that are invoked when the drag is
started and when the user requests that a different operation be applied
to the drop.
@item operation-cursor-icon
Specifies the cursor icon used to designate the type of operation
performed by the drag transaction.
@item source-cursor-icon
Specifies the cursor icon used to represent the source when a dynamic
visual style is used.
@item source-pixmap-icon
Specifies the pixmap icon used to represent the source when a
preregister visual style is used.
@item state-cursor-icon
Specifies the cursor icon used to designate the state of a drop site.
@item top-level-enter-callback
Specifies the list of callbacks that are invoked when the pointer enters
a top-level window or root window (due to changing screens).
@item top-level-leave-callback
Specifies the list of callbacks that are invoked when the pointer leaves
a top-level window or root window (due to changing screens).
@item valid-cursor-foreground
Specifies the foreground pixel value of the cursor when the state is valid.

@end table

@node xm-drop-site, xm-drop-transfer, xm-drag-context, Drag and Drop Widgets
@subsection xm-drop-site

This is the equivalent of the C pseudo-widget @code{XmDropSite},
specifying the location, behavior, and capabilities of a drop site.
Resources are as follows:

@table @code
@item animation-mask
Specifies a mask to use with the pixmap specified by
@code{animation-pixmap} when the animation style is
@code{drag-under-pixmap}.
@item animation-pixmap
Specifies a pixmap for drag-under animation when the animation style is
@code{drag-under-pixmap}.
@item animation-pixmap-depth
@item animation-style
Specifies the drag-under animation style used when a drag enters a valid
drop site.
@item drag-proc
Specifies the procedure that is invoked when the drop site receives a
crossing, motion, or operation changed message.
@item drop-proc
Specifies the procedure that is invoked when a drop (excluding a cancel
or interrupt action) occurs on a drop site regardless of the status of
the drop site.
@item drop-rectangles
Specifies a list of rectangles that describe the shape of a drop site.
@item drop-site-activity
Indicates whether a drop site is active or inactive.
@item drop-site-operations
Specifies the set of valid operations associated with a drop site.
@item drop-site-type
Specifies the type of the drop site.
@item import-targets
Specifies the list of target atoms that this drop site accepts.
@item num-drop-rectangles
@item num-import-targets
@end table

@node xm-drop-transfer,  , xm-drop-site, Drag and Drop Widgets
@subsection xm-drop-transfer

This is the equivalent of the C widget @code{XmDropTransfer}, specifying
information required by the toolkit in order to process and complete a
drop transaction.  Resources are as follows:

@table @code
@item drop-transfers
Specifies the address of an array of drop transfer entry records.
!!!!!!!!!!!!!
@item incremental
Specifies a Boolean value that indicates whether the transfer on the
receiver side uses the Xt incremental selection transfer mechanism
described in @cite{X Toolkit Intrinsics--C Language Interface}.
@item num-drop-transfers
@item transfer-proc
Specifies a procedure of type !!!!!!!!!!!!! that delivers the requested
selection values.
@item transfer-status
Specifies the current status of the drop transfer.
@end table

@node Drag and Drop Internal Information,  , Drag and Drop Widgets, Motif Drag and Drop
@section Drag and Drop Internal Information

The E-Lisp drag-and-drop implementation is pretty straightforward and is,
as much as possible, a direct lifting of the Motif drag-and-drop functionality
into E-Lisp.  The E-Lisp Xt interface (@pxref{Xt Interface Functions}) is
the foundation upon which the drag-and-drop package is based.  The pseudo-
widget @code{XmDropSite} is accessed in E-Lisp (as @code{xm-drop-site})
using the standard widget-access functions; thus, there are no direct
equivalents for @code{XmDropSiteRetrieve} and @code{XmDropSiteRegister}.
The @var{widget} argument in the C functions is replaced by a @var{screen}
argument, specifying the Emacs screen where the drag or drop is taking place.

@node Xt Interface Functions, Improved Pixmap Support, Motif Drag and Drop, top
@chapter Xt Interface Functions

@menu
* Introduction to Xt Interface Functions::
* More About Widgets::
* Widget Types::
* Widget Access Parameters::
* Widget Functions::
* Xt Interface Internal Information::
@end menu

@node Introduction to Xt Interface Functions, More About Widgets, Xt Interface Functions, Xt Interface Functions
@section Introduction to Xt Interface Functions

@dfn{Xt} is a C-language toolkit that sits on top of the low-level
C-language X library @dfn{Xlib} and provides a high-level, object-oriented
interface to X programming.  An Xt program consists of a number of
@dfn{widgets}, each of which encapsulates @dfn{resources} and @dfn{methods}
and typically corresponds to a section of the program's window that has
specific characteristics of its own (such as a label, button, or menu bar).
A resource is simply a named piece of data; a method is a named, callable
function.  Each widget belongs to a @dfn{class}, which defines which
resources and methods exist for that widget.  A typical resource would
specify the size or background color of the widget; a typical method
would specify a function to be called when the widget needs to be redrawn,
or a function to be called when the widget is about to be destroyed.
New widget classes are usually created as a @dfn{subclass} of an existing
class; a subclass inherits all the resources and methods of its parent class
(or @dfn{superclass}) and can add its own resources and methods and/or
redefine the methods and default resource values of its parent class.  It is
possible to create subclasses of subclasses, and so on; in fact, all classes
form a hierarchy and are ultimately derived from the top-level class
@samp{Object}.

The widget paradigm for encapsulating data and functions can, and is,
used for representing other sorts of things than objects on a screen.
Some parts of Era (for example, its Motif drag-and-drop interface) make
heavy use of Xt widgets for representing many different sorts of data.
Era provides a E-Lisp interface to Xt widgets so that the E-Lisp programmer
can take full advantage of the functionality provided.

@node More About Widgets, Widget Types, Introduction to Xt Interface Functions, Xt Interface Functions
@section More About Widgets

In E-Lisp, a widget is represented as an opaque object that can only
be manipulated with a special set of functions.  Every widget has a
set of named resources, some of which are defined by the widget's class
and others of which are inherited from the widget's superclasses.
Furthermore, every widget class has a @dfn{set-values} method, which
is called when a resource is set, and a @dfn{get-values} method, which
is called when the value of a resource is retrieved; thus, setting a
resource or fetching its value can have arbitrary side effects, including
setting other resources, causing changes visible on the screen, etc.

Every resource is typed, and can only hold values that are compatible with
this type (@pxref{Widget Types}).  Furthermore, each resource has a
set of access parameters, specifying what sort of operations can be done
on the resource (specifically, specifying a value at widget creation,
setting a widget's value later on, and retrieving a widget's value).
@xref{Widget Access Parameters}.

@node Widget Types, Widget Access Parameters, More About Widgets, Xt Interface Functions
@section Widget Types

The type of data that a particular resource may contain is specified using
a symbol, a cons, or the constant @code{nil}.  This type may be retrieved
using the function @code{xt-resource-type} (@pxref{Widget Functions}).
Note that the value used to specify the type of the resource's data is
different from the value of the resource itself.

@menu
* Simple Types::
* Compound Types::
* Untyped Data::
@end menu

@node Simple Types, Compound Types, Widget Types, Widget Types
@subsection Simple Types

A simple type is specified by a symbol, as follows:

@table @code
@item 'boolean
One of the values @code{nil} or @code{t}, equivalent to @code{0} and
@code{1} (or any other non-zero value) in C.
@item 'cardinal
A non-negative integer.
@item 'dimension
An integer, used to specify window sizes.
@item 'event
An object of type @code{Lisp_Event}.
@item 'int
An integer.
@item 'pixel
An object of type @code{Lisp_Pixel}.  See function @code{make-pixel}.
@item 'pixmap
An object of type @code{Lisp_Pixmap}.  See function @code{make-pixmap}.
Note that Lisp pixmaps encode the width, height, and depth of the pixmap
as well as its data, and thus there is no Lisp equivalent for the C
resources used to specify these values.
@item 'position
An integer, used to specify window positions.
@item 'screen
An object of type @code{Lisp_Screen}, corresponding to an Emacs "screen"
or top-level X window.  The actual window passed into the C resource is
the window corresponding to the edit area of the specified screen.
@item 'time
A non-negative integer specifying the elapsed time in milliseconds since
the server was started.
@item 'unsigned-int
A non-negative integer.
@end table

@node Compound Types, Untyped Data, Simple Types, Widget Types
@subsection Compound Types

A compound type is specified by a cons whose car is a symbol and whose
cdr is some value (called the @dfn{quantifier}) that refines the type,
typically a list of allowable values.

@table @code
@item 'enum
The quantifier is a list of allowable values; the value of the resource
must be one of these values.
@item 'list
The quantifier is a type; the value of the resource must be either
@code{nil} or a list of values of the specified type.
@item 'resource-list
The quantifier is a list of resource specifications.  Each resource
specification corresponds to one resource and is a list as follows:
@example
@code{(resource-name type default-value &optional access)}
@end example
@item 'set
The quantifier is a list of allowable values; the value of the resource
must be either @code{nil} or a list of one or more of these values.
@item 'struct
The quantifier is a list specifying the fields of a structure.  Each
element of the list is either a (@var{name} . @var{type}) pair or a
symbol specifying a structure type, which causes the elements of that
structure to be included in place as if each had been specified in
turn.  The value of the resource must be either an association list
of (@var{name} . @var{value}) pairs or a vector of values, each one
in turn corresponding to the next field in the original specification.
@end table

@node Untyped Data,  , Compound Types, Widget Types
@subsection Untyped Data

A type of @code{nil} indicates that any data is allowed as the value of
the resource.  This is typically used for client-specified data that will
be passed as one of the arguments to a callback function.

@node Widget Access Parameters, Widget Functions, Widget Types, Xt Interface Functions
@section Widget Access Parameters

@node Widget Functions, Xt Interface Internal Information, Widget Access Parameters, Xt Interface Functions
@section Widget Functions

@defun xt-set-values widget values
Set the resources of @var{widget} according to @var{values}.
This is an interface to XtSetValues().  (A @dfn{widget} is an Xt object
that encapsulates data and functions, and a @dfn{resource} is a named
element of data in a widget; see an Xt reference manual for more
information.)  @var{values} is an alist of (@var{symbol} .  @var{value})
pairs, where @var{symbol} is the name of a valid resource for
@var{widget}, and @var{value} is a possible value for this resource.  An
error occurs if an invalid resource name or a value with an incorrect
type is given, or if a specified resource cannot be set with
xt-set-values; in such a case, no resources are set.  See also
@code{xt-get-values}, @code{xt-widget-class}, @code{xt-resource-list},
@code{xt-resource-type}, and @code{xt-resource-access}.
@end defun

@defun xt-get-values widget resources
Retrieve the values of @var{resources} from @var{widget}.
This is an interface to XtGetValues().  @var{resources} is a list of
resource names.  An alist of (@var{symbol} . @var{value}) pairs is
returned, one for each resource in @var{resources}.  An error occurs if
any resource name is invalid or if a specified resource cannot have its
value retrieved with xt-get-values.  See @code{xt-set-values} for more
information.
@end defun

@defun xt-widget-class widget
Retrieve the class of @var{widget}.
The class of a widget determines the valid resources and methods for
the widget.  See @code{xt-set-values} for more information.
@end defun

@defun xt-resource-list widget-or-class
Retrieve a list of the valid resources for @var{widget-or-class}.
@var{widget-or-class} is either a widget or the name of a widget class.
@end defun

@defun xt-resource-type widget-or-class resource
@end defun

@defun xt-resource-access widget-or-class resource
@end defun

@node Xt Interface Internal Information,  , Widget Functions, Xt Interface Functions
@section Xt Interface Internal Information

@menu
* Introduction to Xt Interface Internal Information::
* Xt Type File Functions::
@end menu

@node Introduction to Xt Interface Internal Information, Xt Type File Functions, Xt Interface Internal Information, Xt Interface Internal Information
@subsection Introduction to Xt Interface Internal Information

Widgets are represented using a "Lisp_Widget" data type.
!!!!!!!!!!!!!!!!!!!!
After that comes type-specific information: in this case
just a pointer to the actual Widget structure.  Lisp_Opaque objects should
also be used for such things as boxed ToolTalk ID's (which are currently
represented as a cons, which is not opaque).

In order to specify the nature of the resources associated with each widget,
a special "widget info" file is used.  This is actually just a .EL file
giving commands that define widgets and types and such.  The result of
executing this file is a number of C-language .h files that can be included
at appropriate points in a .c file, so that everything can remain in C
but can be automated.

In addition, numerous Lisp-to-C and C-to-Lisp conversion functions need to
be written (these are C-language functions).  These are used to convert
resource values when calling xt-get-values and xt-set-values and to convert
callback structures and such.

Lisp callbacks are handled with a singl


@node Xt Type File Functions,  , Introduction to Xt Interface Internal Information, Xt Interface Internal Information
@subsection Xt Type File Functions

@defun type= type-name type-equiv
Specifies that @var{type-name} is the same as the type specified in
@var{type-equiv}.  This is typically used to equate a simple type with
a compound type.
@end defun

@defun typedef type-name &rest properties
Defines a simple type.  Optional arguments specify properties for this type
that are other than the default.  Current properties are:

@table @code
@item no-l2c
There is no Lisp-to-C conversion function.
@item no-c2l
There is no C-to-Lisp conversion function.
@end table

Unless explicitly specified, it is assumed that there are conversion
functions named @samp{C2L_} plus the type name and @samp{L2C_} plus the
type name, for converting between a C type (of type @code{XtArgVal}) and
a Lisp type (of type @code{Lisp_Object}). (Dashes in the Lisp type name
are converted to underscores in the equivalent C type name.)
@end defun

@defun typedef-compound type-name process-quant &rest properties
Defines a compound type.  Properties and conversion functions are like
simple types (see @code{typedef}), with the exception that the
conversion functions both take a second argument of type
@code{XtPointer}, specifying the quantifier that is associated with the
type (see @pxref{Compound Types}).  @var{process-quant} is a Lisp
function that converts the Lisp quantifier into a C quantifier structure
and returns the name of the C structure variable as a string.
@end defun

@defun typedef-struct type-name &rest list
Define an internal structure type.  This is not visible at the C level
and is used only to assist in overlapping structure types in other
definitions.  @var{list} is a list of field definitions, each of which
is either a list @code{(name type)}, specifying the name of the field
and its type, or a symbol, specifying another internal structure type
whose fields are to be inserted in place in this structure.
@end defun

@defun defwidget widget-class super-class resource-list &optional special-p
Define the characteristics of @var{widget-class}, which inherits
resources from its parent class @var{super-class} (possibly @code{nil}).
@var{resource-list} is a list of resource specifications, each of which
specifies the properties of a resource as follows:
@example
@code{(resource-name type default-value &optional access)}
@end example
@var{access} is either @code{nil} (which is equivalent to @code{'(c s g)}) or
a list of one or more of the following symbols:
@table @code
@item c
Resource can be set at creation time.
@item s
Resource can be set with xt-set-values.
@item g
Resource can be retrieved with xt-get-values.
@item d
The default value is "dynamic" (i.e. there is no fixed default value).
@end table
@end defun

@defun defcb reason callback-struct
@end defun

@node Improved Pixmap Support, ToolTalk Support, Xt Interface Functions, top
@chapter Improved Pixmap Support

@menu
* Overview of Improved Pixmap Support::
* New Pixmap Support Functions::
@end menu

@node Overview of Improved Pixmap Support, New Pixmap Support Functions, Improved Pixmap Support, Improved Pixmap Support
@section Overview of Improved Pixmap Support

Emacs 19.8 adds a @samp{pixmap} type, which directly supports pixmaps
under X.  Under E-Lisp, a pixmap object contains the pixmap itself, its
width, height, and depth, a mask, and a hotspot coordinate.  The mask
and hotspot are used when the pixmap is used as a cursor or other
pointing indicator.  The mask is a depth one bitmap of the same
dimensions as the pixmap, specifying the actual shape of this pixmap
within the rectangle defined by its dimensions.  A set bit in the mask
specifies that the corresponding pixel in the pixmap is to be displayed,
while a cleared bit specifies that the background should show through at
that point.  The hotspot is the spot in the pixmap that is aligned with
the logical pointer coordinate.

Support for the various pixmap elements is not complete under Emacs
19.8.  Era adds the settor and accessor functions that were not
previously provided.

@node New Pixmap Support Functions,  , Overview of Improved Pixmap Support, Improved Pixmap Support
@section New Pixmap Support Functions

@defun pixmap-hotspot-x pixmap
Return the X-coordinate of the pixmap's hotspot.  See
@code{set-pixmap-hotspot}.
@refill
@end defun

@defun set-pixmap-hotspot pixmap x y
Set the pixmap's hotspot.  This is a point relative to the origin of the
pixmap.  When a pixmap is used as a cursor or similar pointing
indicator, the hotspot is the point on the pixmap that sits over the
location that the pointer points to.  This is, for example, the tip of
the arrow or the center of the crosshairs.
@end defun

@defun pixmap-hotspot-y pixmap
Return the Y-coordinate of the pixmap's hotspot.  See
@code{set-pixmap-hotspot}.
@refill
@end defun

@defun pixmap-width pixmap
Return the width of the pixmap, in pixels.
@end defun

@defun pixmap-height pixmap
Return the height of the pixmap, in pixels.
@end defun

@defun pixmap-depth pixmap
Return the depth of the pixmap.  This is 0 for a bitmap, or >= 1 for a
pixmap.
@end defun

@defun set-pixmap-data pixmap data
Set the pixmap's data.  The data must be in the form of a list;
currently only the format @samp{(width height data)} is supported.  See
@code{make-pixmap}.
@end defun

@defun set-pixmap-mask pixmap data
Set the pixmap's mask according to the specified data.  The data must be
in XY format and must be at least (width bits long, one bit per pixel in
the pixmap.  When the pixmap is used as a cursor or similar pointing
indicator, the mask indicates which pixels in the pixmap's rectangular
outline are to be taken from the pixmap and which from the background.
@end defun

@node ToolTalk Support, Miscellaneous (for now), Improved Pixmap Support, top
@chapter ToolTalk Support

@menu
* Emacs ToolTalk API Summary::
* Sending Messages::
* Receiving Messages::
@end menu

@node Emacs ToolTalk API Summary, Sending Messages, ToolTalk Support, ToolTalk Support
@section Emacs ToolTalk API Summary

The Emacs Lisp interface to ToolTalk is similar, at least in spirit,
to the standard C ToolTalk API.  Only the message and pattern parts
of the API are supported at present; more of the API could be added
if needed.  The Lisp interface departs from the C API in a few ways:

@itemize @bullet
@item
ToolTalk is initialized automatically at Emacs startup-time.  Messages
can only be sent other ToolTalk applications connected to the same X11
server that emacs is running on.

@item
There are fewer entry points; polymorphic functions with keyword
arguments are used instead.

@item
The callback interface is simpler and marginally less functional.
A single callback may be associated with a message or a pattern;
the callback is specified with a Lisp symbol (the symbol should
have a function binding).

@item
The session attribute for messages and patterns is always 
initialized to the default session.

@item
Anywhere a ToolTalk enum constant, e.g. @samp{TT_SESSION}, is valid, one
can substitute the corresponding symbol, e.g. @code{'TT_SESSION}.  This
simplifies building lists that represent messages and patterns.
@end itemize

@node Sending Messages, Receiving Messages, Emacs ToolTalk API Summary, ToolTalk Support
@section Sending Messages

@menu
* Example of Sending Messages::
* Elisp Interface for Sending Messages::
@end menu

@node Example of Sending Messages, Elisp Interface for Sending Messages, Sending Messages, Sending Messages
@subsection Example of Sending Messages

Here's a simple example that sends a query to another application
and then displays its reply.  Both the query and the reply are
stored in the first argument of the message.

@example
(defun tooltalk-random-query-handler (msg)
  (let ((state (get-tooltalk-message-attribute msg 'state)))
    (cond
      ((eq state 'TT_HANDLED)
       (message (get-tooltalk-message-attribute msg arg_val 0)))
      ((memq state '(TT_FAILED TT_REJECTED))
       (message "Random query turns up nothing")))))

(defvar random-query-message
  '(   class TT_REQUEST 
       scope TT_SESSION 
     address TT_PROCEDURE
          op "random-query"
        args '((TT_INOUT "?" "string"))
    callback tooltalk-random-query-handler))

(let ((m (make-tooltalk-message random-query-message)))
  (send-tooltalk-message m))
@end example

@node Elisp Interface for Sending Messages,  , Example of Sending Messages, Sending Messages
@subsection Elisp Interface for Sending Messages

@defun make-tooltalk-message attributes
Create a ToolTalk message and initialize its attributes.
The value of @var{attributes} must be a list of alternating keyword/values, 
where keywords are symbols that name valid message attributes.  
For example:

@example
  (make-tooltalk-message 
    '(class TT_NOTICE
      scope TT_SESSION
      address TT_PROCEDURE
      op "do-something"
      args ("arg1" 12345 (TT_INOUT "arg3" "string"))))
@end example

Values must always be strings, integers, or symbols that represent
ToolTalk constants.  Attribute names are the same as those supported by
@code{set-tooltalk-message-attribute}, plus @code{args}.

The value of @code{args} should be a list of message arguments where
each message argument has the following form:

@quotation
   @samp{(mode [value [type]])} or just @samp{value}
@end quotation

Where @var{mode} is one of @code{TT_IN}, @code{TT_OUT}, or
@code{TT_INOUT} and @var{type} is a string.  If @var{type} isn't
specified then @code{int} is used if @var{value} is a number; otherwise
@code{string} is used.  If @var{type} is @code{string} then @var{value}
is converted to a string (if it isn't a string already) with
@code{prin1-to-string}.  If only a value is specified then @var{mode}
defaults to @code{TT_IN}.  If @var{mode} is @code{TT_OUT} then
@var{value} and @var{type} don't need to be specified.  You can find out
more about the semantics and uses of ToolTalk message arguments in
chapter 4 of the @cite{ToolTalk Programmer's Guide}.
@refill
@end defun

@defun send-tooltalk-message msg
Send the message on its way.  Once the message has been sent it's almost
always a good idea to get rid of it with
@code{destroy-tooltalk-message}.
@refill
@end defun

@defun return-tooltalk-message msg &optional mode
Send a reply to this message.  The second argument can be @code{reply},
@code{reject} or @code{fail}; the default is @code{reply}.  Before
sending a reply, all message arguments whose mode is @code{TT_INOUT} or
@code{TT_OUT} should have been filled in -- see
@code{set-tooltalk-message-attribute}.
@refill
@end defun

@defun get-tooltalk-message-attribute msg attribute &optional argn
Returns the indicated ToolTalk message attribute.  Attributes are
identified by symbols with the same name (underscores and all) as the
suffix of the ToolTalk @samp{tt_message_<attribute>} function that
extracts the value.  String attribute values are copied and enumerated
type values (except disposition) are converted to symbols;
e.g. @samp{TT_HANDLER} is @code{'TT_HANDLER}, @samp{uid} and @samp{gid}
are represented by fixnums (small integers), @samp{opnum} is converted
to a string, and @samp{disposition} is converted to a fixnum.  We
convert @samp{opnum} (a C int) to a string (e.g. @code{123} @result{}
@code{"123"}) because there's no guarantee that opnums will fit within
the range of Emacs Lisp integers.
@refill

[TBD] Use the @code{plist} attribute instead of C API @code{user}
attribute for user-defined message data.  To retrieve the value of a
message property, specify the indicator for @var{argn}.  For example, to
get the value of a property called @code{rflag}, use

@example
   (get-tooltalk-message-attribute msg 'plist 'rflag)
@end example

To get the value of a message argument use one of the @code{arg_val}
(strings), @code{arg_ival} (integers), or @code{arg_bval} (strings with
embedded nulls), attributes.  For example, to get the integer value of
the third argument:

@example
   (get-tooltalk-message-attribute msg 'arg_ival 2)
@end example

As you can see, argument numbers are zero-based.  The type of each
arguments can be retrieved with the @code{arg_type} attribute; however
ToolTalk doesn't define any semantics for the string value of
@code{arg_type}.  Conventionally @code{string} is used for strings and
@code{int} for 32 bit integers.  Note that Emacs Lisp stores the lengths
of strings explicitly (unlike C) so treating the value returned by
@code{arg_bval} like a string is fine.
@refill
@end defun

@defun set-tooltalk-message-attribute value msg attribute &optional argn
Initialize one ToolTalk message attribute.

Attribute names and values are the same as for
@code{get-tooltalk-message-attribute}.  A property list is provided for
user data (instead of the @code{user} message attribute); see
@code{get-tooltalk-message-attribute}.
@refill

Callbacks are handled slightly differently than in the C ToolTalk API.
The value of @var{callback} should be the name of a function of one
argument.  It will be called each time the state of the message changes.
This is usually used to notice when the message's state has changed to
@code{TT_HANDLED} (or @code{TT_FAILED}), so that reply argument values
can be used.
@refill

If one of the argument attributes is specified as @code{arg_val},
@code{arg_ival}, or @code{arg_bval}, then @var{argn} must be the
number of an already created argument.  Arguments can be added to a
message with @code{add-tooltalk-message-arg}.
@refill
@end defun

@defun add-tooltalk-message-arg msg mode type &optional value
Append one new argument to the message.  @var{mode} must be one of
@code{TT_IN}, @code{TT_INOUT}, or @code{TT_OUT}, @var{type} must be a
string, and @var{value} can be a string or an integer.  ToolTalk doesn't
define any semantics for @var{type}, so only the participants in the
protocol you're using need to agree what types mean (if anything).
Conventionally @code{string} is used for strings and @code{int} for 32
bit integers.  Arguments can initialized by providing a value or with
@code{set-tooltalk-message-attribute}; the latter is neccessary if you
want to initialize the argument with a string that can contain embedded
nulls (use @code{arg_bval}).
@refill
@end defun

@defun create-tooltalk-message
Create a new ToolTalk message.  The message's session attribute is
initialized to the default session.  Other attributes can be intialized
with @code{set-tooltalk-message-attribute}.
@code{make-tooltalk-message} is the preferred way to create and
initialize a message.
@refill
@end defun

@defun destroy-tooltalk-message msg
Apply @samp{tt_message_destroy} to the message.  It's not necessary to
destroy messages after they've been processed by a message or pattern
callback, the Lisp/ToolTalk callback machinery does this for you.
@end defun

@node Receiving Messages,  , Sending Messages, ToolTalk Support
@section Receiving Messages

@menu
* Example of Receiving Messages::
* Elisp Interface for Receiving Messages::
@end menu

@node Example of Receiving Messages, Elisp Interface for Receiving Messages, Receiving Messages, Receiving Messages
@subsection Example of Receiving Messages

Here's a simple example of a handler for a message that tells emacs to
display a string in the mini-buffer area.  The message operation is
called @samp{emacs-display-string}.  Its first (0th) argument is the
string to display.

@example
(defun tooltalk-display-string-handler (msg)
  (message (get-tooltalk-message-attribute msg 'arg_val 0)))

(defvar display-string-pattern
  '(category TT_HANDLE
       scope TT_SESSION
          op "emacs-display-string"
    callback tooltalk-display-string-handler))

(let ((p (make-tooltalk-pattern display-string-pattern)))
  (register-tooltalk-pattern p))
@end example

@node Elisp Interface for Receiving Messages,  , Example of Receiving Messages, Receiving Messages
@subsection Elisp Interface for Receiving Messages

@defun make-tooltalk-pattern attributes
Create a ToolTalk pattern and initialize its attributes.
The value of attributes must be a list of alternating keyword/values, 
where keywords are symbols that name valid pattern attributes
or lists of valid attributes.  For example:

@example
  (make-tooltalk-pattern 
    '(category TT_OBSERVE
         scope TT_SESSION
            op ("operation1" "operation2")
          args ("arg1" 12345 (TT_INOUT "arg3" "string"))))
@end example

Attribute names are the same as those supported by 
@code{add-tooltalk-pattern-attribute}, plus @code{'args}.

Values must always be strings, integers, or symbols that represent
ToolTalk constants or lists of same.  When a list of values is provided
all of the list elements are added to the attribute.  In the example
above, messages whose @samp{op} attribute is @samp{"operation1"} or
@samp{"operation2"} would match the pattern.

The value of @var{args} should be a list of pattern arguments where each
pattern argument has the following form:

@quotation
   @samp{(mode [value [type]])} or just @samp{value}
@end quotation

Where @var{mode} is one of @code{TT_IN}, @code{TT_OUT}, or
@code{TT_INOUT} and @var{type} is a string.  If @var{type} isn't
specified then @code{int} is used if @var{value} is a number; otherwise
@code{string} is used.  If @var{type} is @code{string} then @var{value}
is converted to a string (if it isn't a string already) with
@code{prin1-to-string}.  If only a value is specified then @var{mode}
defaults to @code{TT_IN}.  If @var{mode} is @code{TT_OUT} then
@var{value} and @var{type} don't need to be specified.  You can find out
more about the semantics and uses of ToolTalk pattern arguments in
chapter 3 of the @cite{ToolTalk Programmer's Guide}.
@refill
@end defun

@defun register-tooltalk-pattern pat
Emacs will begin receiving messages that match this pattern.
@end defun

@defun unregister-tooltalk-pattern pat
Emacs will stop receiving messages that match this pattern.
@end defun

@defun add-tooltalk-pattern-attribute value pat indicator
Add one value to the indicated pattern attribute. The names of
attributes are the same as the ToolTalk accessors used to set them less
the @samp{tooltalk_pattern_} prefix and the @samp{_add} suffix.  For
example, the name of the attribute for the
@samp{tt_pattern_disposition_add} attribute is @code{disposition}.  The
@code{category} attribute is handled specially, since a pattern can only
be a member of one category (@code{TT_OBSERVE} or @code{TT_HANDLE}).
@refill

Callbacks are handled slightly differently than in the C ToolTalk API.
The value of @var{callback} should be the name of a function of one
argument.  It will be called each time the pattern matches an incoming
message.
@end defun

@defun add-tooltalk-pattern-arg pat mode type value
Add one fully-specified argument to a ToolTalk pattern.  @var{mode} must
be one of @code{TT_IN}, @code{TT_INOUT}, or @code{TT_OUT}.  @var{type}
must be a string.  @var{value} can be an integer, string or @code{nil}.
If @var{value} is an integer then an integer argument
(@samp{tt_pattern_iarg_add}) is added; otherwise a string argument is
added.  At present there's no way to add a binary data argument.
@refill
@end defun

@defun create-tooltalk-pattern
Create a new ToolTalk pattern and initialize its session attribute to
be the default session.
@end defun

@defun destroy-tooltalk-pattern pat
Apply @samp{tt_pattern_destroy} to the pattern.  This effectively
unregisters the pattern.
@end defun

@defun describe-tooltalk-message msg &optional stream
Print the message's attributes and arguments to @var{stream}.  This is
often useful for debugging.
@end defun


@node Miscellaneous (for now),  , ToolTalk Support, top
@chapter Miscellaneous (for now)

There is now a variable and a function @code{era-version}.  These are the
Era equivalent to @code{emacs-version}.  @code{emacs-version} will be
removed at some future date as Era comes closer to completion.

To disable warnings about not being able to deduce different types of fonts
whenever a screen is created, set @code{x-inhibit-font-complaints} to
@code{'t}.  This will only disable the warnings for cloned screens, not the
initially created screen.


@page
@shortcontents
@contents
@bye

