Function: compose-region

compose-region is an interactive and byte-compiled function defined in composite.el.gz.

Signature

(compose-region START END &optional COMPONENTS MODIFICATION-FUNC)

Documentation

Compose characters in the current region.

Characters are composed relatively, i.e. composed by overstriking or stacking depending on ascent, descent and other metrics of glyphs.

For instance, if the region has three characters "XYZ", X is regarded as BASE glyph, and Y is displayed:
  (1) above BASE if Y's descent value is not positive
  (2) below BASE if Y's ascent value is not positive
  (3) on BASE (i.e. at the BASE position) otherwise
and Z is displayed with the same rule while regarding the whole XY glyphs as BASE.

When called from a program, expects these four arguments.

First two arguments START and END are positions (integers or markers) specifying the region.

Optional 3rd argument COMPONENTS, if non-nil, is a character, a string or a vector or list of integers and rules.

If it is a character, it is an alternate character to display instead of the text in the region.

If it is a string, the elements are alternate characters. In this case, TAB element has a special meaning. If the first character is TAB, the glyphs are displayed with left padding space so that no pixel overlaps with the previous column. If the last character is TAB, the glyphs are displayed with right padding space so that no pixel overlaps with the following column.

If it is a vector or list, it is a sequence of alternate characters and composition rules, where (2N)th elements are characters and (2N+1)th elements are composition rules to specify how to compose (2N+2)th elements with previously composed N glyphs.

A composition rule is a cons of global and new glyph reference point symbols. See the documentation of reference-point-alist for more details.

Optional 4th argument MODIFICATION-FUNC is a function to call to adjust the composition when it gets invalid because of a change of text in the composition.

Probably introduced at or before Emacs version 21.1.

Key Bindings

Source Code

;; Defined in /usr/src/emacs/lisp/composite.el.gz
(defun compose-region (start end &optional components modification-func)
  "Compose characters in the current region.

Characters are composed relatively, i.e. composed by overstriking
or stacking depending on ascent, descent and other metrics of
glyphs.

For instance, if the region has three characters \"XYZ\", X is
regarded as BASE glyph, and Y is displayed:
  (1) above BASE if Y's descent value is not positive
  (2) below BASE if Y's ascent value is not positive
  (3) on BASE (i.e. at the BASE position) otherwise
and Z is displayed with the same rule while regarding the whole
XY glyphs as BASE.

When called from a program, expects these four arguments.

First two arguments START and END are positions (integers or markers)
specifying the region.

Optional 3rd argument COMPONENTS, if non-nil, is a character, a string
or a vector or list of integers and rules.

If it is a character, it is an alternate character to display instead
of the text in the region.

If it is a string, the elements are alternate characters.  In
this case, TAB element has a special meaning.  If the first
character is TAB, the glyphs are displayed with left padding space
so that no pixel overlaps with the previous column.  If the last
character is TAB, the glyphs are displayed with right padding
space so that no pixel overlaps with the following column.

If it is a vector or list, it is a sequence of alternate characters and
composition rules, where (2N)th elements are characters and (2N+1)th
elements are composition rules to specify how to compose (2N+2)th
elements with previously composed N glyphs.

A composition rule is a cons of global and new glyph reference point
symbols.  See the documentation of `reference-point-alist' for more
details.

Optional 4th argument MODIFICATION-FUNC is a function to call to
adjust the composition when it gets invalid because of a change of
text in the composition."
  (interactive "r")
  (let ((modified-p (buffer-modified-p))
	(inhibit-read-only t))
    (if (or (vectorp components) (listp components))
	(setq components (encode-composition-components components)))
    (compose-region-internal start end components modification-func)
    (restore-buffer-modified-p modified-p)))