@chapter Glyphs
@cindex glyphs
- A @dfn{glyph} is an object that is used for pixmaps and images of all
-sorts, as well as for things that ``act'' like pixmaps, such as
-non-textual strings (@dfn{annotations}) displayed in a buffer or in the
-margins. It is used in begin-glyphs and end-glyphs attached to extents,
-marginal and textual annotations, overlay arrows (@code{overlay-arrow-*}
-variables), toolbar buttons, mouse pointers, frame icons, truncation and
-continuation markers, and the like. (Basically, any place there is an
-image or something that acts like an image, there will be a glyph object
-representing it.)
+ A @dfn{glyph} is an object that is used for pixmaps, widgets and
+images of all sorts, as well as for things that ``act'' like pixmaps,
+such as non-textual strings (@dfn{annotations}) displayed in a buffer or
+in the margins. It is used in begin-glyphs and end-glyphs attached to
+extents, marginal and textual annotations, overlay arrows
+(@code{overlay-arrow-*} variables), toolbar buttons, mouse pointers,
+frame icons, truncation and continuation markers, and the
+like. (Basically, any place there is an image or something that acts
+like an image, there will be a glyph object representing it.)
The actual image that is displayed (as opposed to its position or
clipping) is defined by an @dfn{image specifier} object contained
* Redisplay Glyphs:: Glyphs controlling various redisplay functions.
* Subwindows:: Inserting an externally-controlled subwindow
into a buffer.
+* Glyph Examples:: Examples of how to work with glyphs.
@end menu
@node Glyph Functions
toolbar, or elsewhere in a buffer), @code{pointer} (used for the
mouse-pointer), or @code{icon} (used for a frame's icon), and defaults
to @code{buffer}. @xref{Glyph Types}.
+
+A glyph in XEmacs does @strong{NOT} refer to a single unit of textual
+display (the XEmacs term for this is @dfn{rune}), but rather is an
+object encapsulating a graphical element, such as an image or widget (an
+element such as a button or text field; @dfn{widget} is the term for
+this under X Windows, and it's called a @dfn{control} under MS Windows).
+This graphical element could appear in a buffer, a margin, a gutter, or
+a toolbar, or as a mouse pointer or an icon, for example.
+
+Creating a glyph using @code{make-glyph} does not specify @emph{where}
+the glyph will be used, but it does specify @emph{what} the glyph will
+look like. In particular, @var{spec-list} is used to specify this, and it's
+used to initialize the glyph's @code{image} property, which is an image
+specifier. (Note that @dfn{image} as used in the context of a glyph's
+@code{image} property or in the terms @dfn{image specifier}, @dfn{image
+instantiator}, or @dfn{image instance} does not refer to what people
+normally think of as an image (which in XEmacs is called a
+@dfn{pixmap}), but to any graphical element---a pixmap, a widget, or
+even a block of text, when used in the places that call for a glyph.)
+The format of the @var{spec-list} is typically an image instantiator (a string
+or a vector; @ref{Image Specifiers}), but can also be a list of such
+instantiators (each one in turn is tried until an image is successfully
+produced), a cons of a locale (frame, buffer, etc.) and an
+instantiator, a list of such conses, or any other form accepted by
+@code{canonicalize-spec-list}. @xref{Specifiers}, for more information
+about specifiers.
+
+If you're not familiar with specifiers, you should be in order to
+understand how glyphs work. The clearest introduction to specifiers
+is in the Lispref manual, available under Info. (Choose
+Help->Info->Info Contents on the menubar or type C-h i.) You can
+also see @code{make-specifier} for a capsule summary. What's important to
+keep in mind is that a specifier lets you set a different value for
+any particular buffer, window, frame, device, or console. This allows
+for a great deal of flexibility; in particular, only one global glyph
+needs to exist for a particular purpose (e.g. the icon used to represent
+an iconified frame, the mouse pointer used over particular areas of a
+frame, etc.), and in these cases you do not create your own glyph, but
+rather modify the existing one.
+
+As well as using @var{spec-list} to initialize the glyph, you can set
+specifications using @code{set-glyph-image}. Note that, due to a
+possibly questionable historical design decision, a glyph itself is not
+actually a specifier, but rather is an object containing an image
+specifier (as well as other, seldom-used properties). Therefore, you
+cannot set or access specifications for the glyph's image by directly
+using @code{set-specifier}, @code{specifier-instance} or the like on the
+glyph; instead use them on @code{(glyph-image @var{glyph})} or use the
+convenience functions @code{set-glyph-image},
+@code{glyph-image-instance}, and @code{glyph-image}.
+
+Once you have created a glyph, you specify where it will be used as
+follows:
+
+@itemize @bullet
+@item
+To insert a glyph into a buffer, create an extent in the buffer and then
+use @code{set-extent-begin-glyph} or @code{set-extent-end-glyph} to set
+a glyph to be displayed at the corresponding edge of the extent. (It is
+common to create zero-width extents for this purpose.)
+
+@item
+To insert a glyph into the left or right margin of a buffer, first
+make sure the margin is visible by setting a value for the specifiers
+@code{left-margin-width} or @code{right-margin-width}. (Not strictly necessary
+when using margin glyphs with layout policy @code{whitespace}.) Then follow
+the same procedure above for inserting a glyph in a buffer, and then
+set a non-default layout policy for the glyph using
+@code{set-extent-begin-glyph-layout} or @code{set-extent-end-glyph-layout}.
+Alternatively, use the high-level annotations API (see
+@code{make-annotation}). (In point of fact, you can also use the annotations
+API for glyphs in a buffer, by setting a layout policy of @code{text}.)
+
+@item
+To insert a glyph into the modeline, just put the glyph directly as one
+of the modeline elements. (Unfortunately you can't currently put a begin
+glyph or end glyph on one of the modeline extents---they're ignored.)
+
+@item
+To insert a glyph into a toolbar, specify it as part of a toolbar
+instantiator (typically set on the specifier @code{default-toolbar}).
+See @code{default-toolbar} for more information. (Note that it is
+standard practice to use a symbol in place of the glyph list in the
+toolbar instantiator; the symbol is evalled to get the glyph list. This
+facilitates both creating the toolbar instantiator and modifying
+individual glyphs in a toolbar later on. For example, you can change
+the way that the Mail toolbar button looks by modifying the value of the
+variable @code{toolbar-mail-icon} (in general, @code{toolbar-*-icon})
+and then calling @code{(set-specifier-dirty-flag default-toolbar)}.
+(#### Unfortunately this doesn't quite work the way it should; the
+change will appear in new frames, but not existing ones.
+
+@item
+To insert a glyph into a gutter, create or modify a gutter instantiator
+(typically set on the specifier @code{default-gutter}). Gutter
+instantiators consist of strings or lists of strings, so to insert a
+glyph, create an extent over the string, and use
+@code{set-extent-begin-glyph} or @code{set-extent-end-glyph} to set a
+glyph to be displayed at the corresponding edge of the extent, just like
+for glyphs in a buffer.
+
+@item
+To use a glyph as the icon for a frame, you do not actually create a new
+glyph; rather, you change the specifications for the existing glyph
+@code{frame-icon-glyph}. (Remember that, because of the specifier nature
+of glyphs, you can set different values for any particular buffer or
+frame.)
+
+@item
+To use a glyph as the mouse pointer, in general you do not create a new
+glyph, but rather you change the specifications of various existing
+glyphs, such as @code{text-pointer-glyph} for the pointer used over
+text, @code{modeline-pointer-glyph} for the pointer used over the
+modeline, etc. Do an apropos over @code{*-pointer-glyph} to find all of
+them. (Note also that you can temporarily set the mouse pointer to some
+specific shape by using @code{set-frame-pointer}, which takes an image
+instance, as obtained from calling @code{glyph-image-instance} on a glyph
+of type @code{pointer} -- either one of the above-mentioned variables or
+one you created yourself. (See below for what it means to create a
+glyph of type @code{pointer}.) This pointer will last only until the
+next mouse motion event is processed or certain other things happen,
+such as creating or deleting a window. (In fact, the above-mentioned
+pointer glyph variables are implemented as part of the default handler
+for mouse motion events. If you want to customize this behavior, take a
+look at @code{mode-motion-hook}, or @code{mouse-motion-handler} if you
+really want to get low-level.)
+
+@item
+To use a glyph to control the shape of miscellaneous redisplay effects
+such as the truncation and continuation markers, set the appropriate
+existing glyph variables, as for icons and pointers above. See
+@code{continuation-glyph}, @code{control-arrow-glyph},
+@code{hscroll-glyph}, @code{invisible-text-glyph},
+@code{octal-escape-glyph}, and @code{truncation-glyph}. See also
+@code{overlay-arrow-string}, an odd redisplay leftover which can be set
+to a glyph you created, and will cause the glyph to be displayed on top
+of the text position specified in the marker stored in
+@code{overlay-arrow-position}.
+
+@item
+To use a glyph in a display table (i.e. to control the appearance of any
+individual character), create the appropriate character glyphs and then
+set a specification for the specifier @code{current-display-table},
+which controls the appearance of characters. You can also set an
+overriding display table for use with text displayed in a particular
+face; see @code{set-face-display-table} and @code{make-display-table}.
+#### Note: Display tables do not currently support general Mule
+characters. They will be overhauled at some point to support this
+and to provide other features required under Mule.
+
+@item
+To use a glyph as the background pixmap of a face: Note that the
+background pixmap of a face is actually an image specifier -- probably
+the only place in XEmacs where an image specifier occurs outside of a
+glyph. Similarly to how the glyph's image specifier works, you don't
+create your own image specifier, but rather add specifications to the
+existing one (using @code{set-face-background-pixmap}). Note that the
+image instance that is generated in order to actually display the
+background pixmap is of type @code{mono-pixmap}, meaning that it's a
+two-color image and the foreground and background of the image get
+filled in with the corresponding colors from the face.
+@end itemize
+
+It is extremely rare that you will ever have to specify a value for
+@var{type}, which should be one of @code{buffer} (used for glyphs in an
+extent, the modeline, the toolbar, or elsewhere in a buffer),
+@code{pointer} (used for the mouse-pointer), or @code{icon} (used for a
+frame's icon), and defaults to @code{buffer}. The only cases where it
+needs to be specified is when creating icon or pointer glyphs, and in
+both cases the necessary glyphs have already been created at startup and
+are accessed through the appropriate variables,
+e.g. @code{text-pointer-glyph} (or in general, @code{*-pointer-glyph})
+and @code{frame-icon-glyph}. @xref{Glyph Types}.
@end defun
@defun make-glyph-internal &optional type
@end defun
@defun make-pointer-glyph &optional spec-list
-This function is equivalent to calling @code{make-glyph} with a
-@var{type} of @code{pointer}.
+
+Return a new @code{pointer-glyph} object with the specification list
+@var{spec-list}. This function is equivalent to calling
+@code{make-glyph} with a @var{type} of @code{pointer}.
+
+It is extremely unlikely that you will ever need to create a pointer
+glyph. Instead, you probably want to be calling @code{set-glyph-image}
+on an existing glyph, e.g. @code{text-pointer-glyph}.
@end defun
@defun make-icon-glyph &optional spec-list
-This function is equivalent to calling @code{make-glyph} with a
-@var{type} of @code{icon}.
+
+Return a new @code{pointer-glyph} object with the specification list
+@var{spec-list}. This function is equivalent to calling
+@code{make-glyph} with a @var{type} of @code{icon}.
+
+It is extremely unlikely that you will ever need to create a pointer
+glyph. Instead, you probably want to be calling @code{set-glyph-image}
+on an existing glyph, e.g. @code{text-pointer-glyph}.
@end defun
@node Glyph Properties
@end defun
@defun make-image-specifier spec-list
-This function creates a new image specifier object and initializes
-it according to @var{spec-list}. It is unlikely that you will ever
-want to do this, but this function is provided for completeness and
-for experimentation purposes. @xref{Specifiers}.
+This function creates a new image specifier object and initializes it
+according to @var{spec-list}. @xref{Specifiers}.
+
+Note that, in practice, you rarely, if ever, need to actually create an
+image specifier! (This function exists mainly for completeness.) Pretty
+much the only use for image specifiers is to control how glyphs are
+displayed, and the image specifier associated with a glyph (the
+@code{image} property of a glyph) is created automatically when a glyph
+is created and need not (and cannot, for that matter) ever be changed
+(@pxref{Glyphs}). In fact, the design decision to create a separate
+image specifier type, rather than make glyphs themselves be specifiers,
+is debatable---the other properties of glyphs are rarely used and could
+conceivably have been incorporated into the glyph's instantiator. The
+rarely used glyph types (buffer, pointer, icon) could also have been
+incorporated into the instantiator.
@end defun
Image instantiators come in many formats: @code{xbm}, @code{xpm},
of the form @samp{@var{font} fontname index [[mask-font] mask-index]}.
Only if X support was compiled into this XEmacs. Currently can only be
instanced as @code{pointer}, although this should probably be fixed.
+@item mswindows-resource
+An MS Windows pointer resource. Specifies a resource to retrieve
+directly from the system (an OEM resource) or from a file, particularly
+an executable file. If the resource is to be retrieved from a file, use
+:file and optionally :resource-id. Otherwise use :resource-id. Always
+specify :resource-type to specify the type (cursor, bitmap or icon) of
+the resource. Possible values for :resource-id are listed below. Can
+be instanced as @code{pointer} or @code{color-pixmap}.
@item subwindow
-An embedded X window; not currently implemented.
+An embedded windowing system window. Can only be instanced as
+@code{subwindow}.
+@item button
+A button widget; either a push button, radio button or toggle button.
+Can only be instanced as @code{widget}.
+@item combo-box
+A drop list of selectable items in a widget, for editing text.
+Can only be instanced as @code{widget}.
+@item edit-field
+A text editing widget. Can only be instanced as @code{widget}.
+@item label
+A static, text-only, widget; for displaying text. Can only be instanced
+as @code{widget}.
+@item layout
+A widget for controlling the positioning of children underneath it.
+Through the use of nested layouts, a widget hierarchy can be created
+which can have the appearance of any standard dialog box or similar
+arrangement; all of this is counted as one @dfn{glyph} and could appear
+in many of the places that expect a single glyph. Can only be instanced
+as @code{widget}.
+@item native-layout
+@c #### Document me better!
+The native version of a layout widget.
+Can only be instanced as @code{widget}.
+@item progress-gauge
+A sliding widget, for showing progress. Can only be instanced as
+@code{widget}.
+@item tab-control
+A tab widget; a series of user selectable tabs. Can only be instanced
+as @code{widget}.
+@item tree-view
+A folding widget. Can only be instanced as @code{widget}.
+@item scrollbar
+A scrollbar widget. Can only be instanced as @code{widget}.
@item autodetect
XEmacs tries to guess what format the data is in. If X support exists,
the data string will be checked to see if it names a filename. If so,
valid cursor-font name, the image will be created as a pointer.
Otherwise, the image will be displayed as text. If no X support exists,
the image will always be displayed as text.
+@item inherit
+Inherit from the background-pixmap property of a face. Can only be
+instanced as @code{mono-pixmap}.
@end table
The valid keywords are:
symbolic color (in the form of a string or a color-specifier object).
If this is not specified, the contents of @code{xpm-color-symbols} are
used to generate the alist.
+@item :resource-id
+Only for @code{mswindows-resource}. This must be either an integer
+(which directly specifies a resource number) or a string. Valid strings
+are
+
+For bitmaps:
+
+"close", "uparrow", "dnarrow", "rgarrow", "lfarrow",
+"reduce", "zoom", "restore", "reduced", "zoomd",
+"restored", "uparrowd", "dnarrowd", "rgarrowd", "lfarrowd",
+"mnarrow", "combo", "uparrowi", "dnarrowi", "rgarrowi",
+"lfarrowi", "size", "btsize", "check", "checkboxes", and
+"btncorners".
+
+For cursors:
+
+"normal", "ibeam", "wait", "cross", "up", "sizenwse",
+"sizenesw", "sizewe", "sizens", "sizeall", and "no".
+
+For icons:
+
+"sample", "hand", "ques", "bang", "note", and "winlogo".
+@item :resource-type
+Only for @code{mswindows-resource}. This must be a symbol, either
+@code{cursor}, @code{icon}, or @code{bitmap}, specifying the type of
+resource to be retrieved.
+@item :face
+Only for @code{inherit}. This specifies the face to inherit from. For
+widgets this also specifies the face to use for display. It defaults to
+gui-element-face.
@end table
+Keywords accepted as menu item specs are also accepted by widgets.
+These are @code{:selected}, @code{:active}, @code{:suffix},
+@code{:keys}, @code{:style}, @code{:filter}, @code{:config},
+@code{:included}, @code{:key-sequence}, @code{:accelerator},
+@code{:label} and @code{:callback}.
+
If instead of a vector, the instantiator is a string, it will be
converted into a vector by looking it up according to the specs in the
@code{console-type-image-conversion-list} for the console type of
does not need to exist at any other time (e.g. it may safely be a
temporary file).
-@defun valid-image-instantiator-format-p format
+@defun valid-image-instantiator-format-p format &optional locale
This function returns non-@code{nil} if @var{format} is a valid image
-instantiator format. Note that the return value for many formats listed
-above depends on whether XEmacs was compiled with support for that format.
+instantiator format.
+
+If @var{locale} is non-@code{nil} then the format is checked in that locale.
+If @var{locale} is @code{nil} the current console is used.
+
+Note that the return value for many formats listed above depends on
+whether XEmacs was compiled with support for that format.
@end defun
@defun image-instantiator-format-list
@end defvar
@defvar x-bitmap-file-path
-A list of the directories in which X bitmap files may be found. If nil,
+A list of the directories in which X bitmap files may be found. If @code{nil},
this is initialized from the @samp{"*bitmapFilePath"} resource. This is
used by the @code{make-image-instance} function (however, note that if
the environment variable @samp{XBMLANGPATH} is set, it is consulted
instance of type @code{nothing}.
@end defun
+@defun widget-image-instance-p object
+Return @code{t} if @var{object} is an image instance of type @code{widget}.
+@end defun
+
@node Image Instance Functions
@subsubsection Image Instance Functions
-@defun make-image-instance data &optional device dest-types no-error
+@defun make-image-instance data &optional domain dest-types noerror
This function creates a new image-instance object.
@var{data} is an image instantiator, which describes the image
by @code{mono-pixmap}, followed by @code{pointer}. For the string and
formatted-string formats, the most natural types are @code{text},
followed by @code{mono-pixmap} (not currently implemented), followed by
-@code{color-pixmap} (not currently implemented). The other formats can
-only be instantiated as one type. (If you want to control more
-specifically the order of the types into which an image is instantiated,
-just call @code{make-image-instance} repeatedly until it succeeds,
-passing less and less preferred destination types each time.
+@code{color-pixmap} (not currently implemented). For MS Windows
+resources, the most natural type for pointer resources is
+@code{pointer}, and for the others it's @code{color-pixmap}. The other
+formats can only be instantiated as one type. (If you want to control
+more specifically the order of the types into which an image is
+instantiated, just call @code{make-image-instance} repeatedly until it
+succeeds, passing less and less preferred destination types each time.
If @var{dest-types} is omitted, all possible types are allowed.
-@var{no-error} controls what happens when the image cannot be generated.
-If @var{nil}, an error message is generated. If @var{t}, no messages
-are generated and this function returns @var{nil}. If anything else, a
-warning message is generated and this function returns @var{nil}.
+@var{domain} specifies the domain to which the image instance will be
+attached. This domain is termed the @dfn{governing domain}. The type
+of the governing domain depends on the image instantiator
+format. (Although, more correctly, it should probably depend on the
+image instance type.) For example, pixmap image instances are specific
+to a device, but widget image instances are specific to a particular
+XEmacs window because in order to display such a widget when two windows
+onto the same buffer want to display the widget, two separate underlying
+widgets must be created. (That's because a widget is actually a child
+window-system window, and all window-system windows have a unique
+existence on the screen.) This means that the governing domain for a
+pixmap image instance will be some device (most likely, the only
+existing device), whereas the governing domain for a widget image
+instance will be some XEmacs window.
+
+If you specify an overly general @var{domain} (e.g. a frame when a
+window was wanted), an error is signaled. If you specify an overly
+specific @var{domain} (e.g. a window when a device was wanted), the
+corresponding general domain is fetched and used instead. For
+@code{make-image-instance}, it makes no difference whether you specify
+an overly specific domain or the properly general domain derived from
+it. However, it does matter when creating an image instance by
+instantiating a specifier or glyph (e.g. with
+@code{glyph-image-instance}), because the more specific domain causes
+spec lookup to start there and proceed to more general domains. (It
+would also matter when creating an image instance with an instantiator
+format of @code{inherit}, but we currently disallow this. #### We should
+fix this.)
+n
+If omitted, @var{domain} defaults to the selected window.
+
+@var{noerror} controls what happens when the image cannot be generated.
+If @code{nil}, an error message is generated. If @code{t}, no messages
+are generated and this function returns @code{nil}. If anything else, a
+warning message is generated and this function returns @code{nil}.
@end defun
@defun colorize-image-instance image-instance foreground background
This function returns the name of the given image instance.
@end defun
+@defun image-instance-domain image-instance
+
+Return the governing domain of the given @var{image-instance}. The
+governing domain of an image instance is the domain that the image
+instance is specific to. It is @emph{NOT} necessarily the domain that
+was given to the call to @code{specifier-instance} that resulted in the
+creation of this image instance. See @code{make-image-instance} for
+more information on governing domains.
+@end defun
+
+
@defun image-instance-string image-instance
This function returns the string of the given image instance. This will
only be non-@code{nil} for text image instances.
@defun subwindowp object
This function returns non-@code{nil} if @var{object} is a subwindow.
@end defun
+
+@node Glyph Examples
+@section Glyph Examples
+
+For many applications, displaying graphics is a simple process: you
+create a glyph, and then you insert it into a buffer.
+
+The easiest way to create a glyph is to use a file that contains a
+graphical image, such as a JPEG, TIFF, or PNG file:
+
+@lisp
+;; Create a glyph from a JPEG file:
+(setq foo (make-glyph [jpeg :file "/tmp/file1.jpg"]))
+@end lisp
+
+@lisp
+;; Create a glyph from a XPM file:
+(setq foo (make-glyph [xpm :file "/tmp/file2.xpm"]))
+@end lisp
+
+@lisp
+;; Create a glyph from a PNG file:
+(setq foo (make-glyph [png :file "/tmp/file3.png"]))
+@end lisp
+
+@lisp
+;; Create a glyph from a TIFF file:
+(setq foo (make-glyph [tiff :file "/tmp/file4.tiff"]))
+@end lisp
+
+The parameters passed to @code{make-glyph} are called "Image
+Specifiers", and can handle more image types than those shown above.
+You can also put the raw image data into a string (e.g., if you put the
+contents of a JPEG file into a string), and use that to create a glyph.
+@xref{Image Specifiers}, for more information.
+
+@quotation
+@strong{Caution}: In order for XEmacs to read a particular graphics file
+format, support for that format must have been compiled into XEmacs.
+It's possible, although somewhat unlikely, for XEmacs to have been
+compiled without support for any of the various graphics file formats.
+To see what graphics formats your particular version of XEmacs supports,
+use @kbd{M-x describe-installation}.
+
+To programmatically query whether or not a particular file format is
+supported, you can use the @code{featurep} function, with one of:
+@code{gif}, @code{tiff}, @code{jpeg}, @code{xpm}, @code{xbm},
+@code{png}, or @code{xface}. For an up-to-date list, @ref{Image
+Specifiers}. Example:
+
+@example
+;; Returns `t' if TIFF is supported:
+(featurep 'tiff)
+@end example
+
+Another example is:
+
+@example
+;; Returns a list of `t' or `nil', depending on whether or not the
+;; corresponding feature is supported:
+(mapcar #'(lambda (format-symbol) (featurep format-symbol))
+ '(gif tiff jpeg xpm png))
+@end example
+
+@end quotation
+
+Once you have a glyph, you can then insert it into a buffer. Example:
+
+@lisp
+;; Use this function to insert a glyph at the left edge of point in the
+;; current buffer. Any existing glyph at this location is replaced.
+(defun insert-glyph (gl)
+ "Insert a glyph at the left edge of point."
+ (let ( (prop 'myimage) ;; myimage is an arbitrary name, chosen
+ ;; to (hopefully) not conflict with any
+ ;; other properties. Change it if
+ ;; necessary.
+ extent )
+ ;; First, check to see if one of our extents already exists at
+ ;; point. For ease-of-programming, we are creating and using our
+ ;; own extents (multiple extents are allowed to exist/overlap at the
+ ;; same point, and it's quite possible for other applications to
+ ;; embed extents in the current buffer without your knowledge).
+ ;; Basically, if an extent, with the property stored in "prop",
+ ;; exists at point, we assume that it is one of ours, and we re-use
+ ;; it (this is why it is important for the property stored in "prop"
+ ;; to be unique, and only used by us).
+ (if (not (setq extent (extent-at (point) (current-buffer) prop)))
+ (progn
+ ;; If an extent does not already exist, create a zero-length
+ ;; extent, and give it our special property.
+ (setq extent (make-extent (point) (point) (current-buffer)))
+ (set-extent-property extent prop t)
+ ))
+ ;; Display the glyph by storing it as the extent's "begin-glyph".
+ (set-extent-property extent 'begin-glyph gl)
+ ))
+
+;; You can then use this function like:
+(insert-glyph (make-glyph [jpeg :file "/tmp/file1.jpg"]))
+;; This will insert the glyph at point.
+
+;; Here's an example of how to insert two glyphs side-by-side, at point
+;; (using the above code):
+(progn
+ (insert-glyph (make-glyph [jpeg :file "/tmp/file1.jpg"]))
+ ;; Create a new extent at point. We can't simply call "insert-glyph",
+ ;; as "insert-glyph" will simply replace the first glyph with the
+ ;; second.
+ (setq extent (make-extent (point) (point) (current-buffer)))
+ ;; Here, we're only setting the 'myimage property in case we need
+ ;; to later identify/locate/reuse this particular extent.
+ (set-extent-property extent 'myimage t)
+ (set-extent-property extent 'begin-glyph
+ (make-glyph [jpeg :file "/tmp/file2.jpg"]))
+ )
+
+@end lisp
+
+Here are the gory details:
+
+@itemize @bullet
+
+@item
+Glyphs are displayed by attaching them to extents (see @ref{Extents}),
+either to the beginning or the end of extents.
+
+Note that extents can be used for many things, and not just for
+displaying images (although, in the above example, we are creating our
+own extent for the sole purpose of displaying an image). Also, note
+that multiple extents are allowed to exist at the same position, and
+they can overlap.
+
+@item
+Glyphs are often displayed inside the text area (alongside text). This
+is the default.
+
+Although glyphs can also be displayed in the margins, how to do this
+will not be described here. For more information on this, see
+@ref{Annotation Basics} (look for information on "layout types") and
+@ref{Extent Properties} (look for @code{begin-glyph-layout} and
+@code{end-glyph-layout}).
+
+@item
+The easiest way to insert a glyph into text is to create a zero-length
+extent at the point where you want the glyph to appear.
+
+Note that zero-length extents are attached to the character to the
+right of the extent; deleting this character will also delete the extent.
+
+@item
+It's often a good idea to assign a unique property to the newly-created
+extent, in case you later want to locate it, and replace any existing
+glyph with a different one (or just delete the existing one). In the
+above example, we are using "myimage" as our (hopefully) unique property
+name.
+
+If you need to locate all of the extents, you'll have to use functions
+like @code{extent-list} or @code{next-extent}, or provide additional
+parameters to the @code{extent-at} function. Assigning a unique
+property to the extent makes it easy to locate your extents; for
+example, @code{extent-list} can return only those extents with a
+particular property. @xref{Finding Extents}, and @ref{Mapping Over
+Extents}, for more information.
+
+@item
+Glyphs are displayed by assigning then to the @code{begin-glyph} or
+@code{end-glyph} property of the extent. For zero-length extents, it
+doesn't really matter if you assign the glyph to the @code{begin-glyph}
+or @code{end-glyph} property, as they are both at the same location;
+however, for non-zero-length extents (extents that cover one or more
+characters of text), it does matter which one you use.
+
+Assigning @code{nil} to the @code{begin-glyph} or @code{end-glyph}
+property will delete any existing glyph. In this case, you may also
+want to delete the extent, assuming that the extent is used for no other
+purpose.
+
+@item
+If you happen to insert two glyphs, side-by-side, note that the example
+@code{insert-glyph} function will have trouble, if it's again used at
+the same point (it can only locate one of the two extents).
+@xref{Finding Extents}, and @ref{Mapping Over Extents}, for more
+information on locating extents in a buffer.
+
+@item
+Among other things, glyphs provide a way of displaying graphics
+alongside text. Note, however, that glyphs only provide a way of
+displaying graphics; glyphs are not actually part of the text, and are
+only displayed alongside the text. If you save the text in the buffer,
+the graphics are not saved. The low-level glyph code does not provide a
+way of saving graphics with the text. If you need to save graphics and
+text, you have to write your own code to do this, and this topic is
+outside the scope of this discussion.
+
+@end itemize
projects / chise / xemacs-chise.git.1 / blobdiff