1 This is ../info/internals.info, produced by makeinfo version 4.0 from
2 internals/internals.texi.
4 INFO-DIR-SECTION XEmacs Editor
6 * Internals: (internals). XEmacs Internals Manual.
9 Copyright (C) 1992 - 1996 Ben Wing. Copyright (C) 1996, 1997 Sun
10 Microsystems. Copyright (C) 1994 - 1998 Free Software Foundation.
11 Copyright (C) 1994, 1995 Board of Trustees, University of Illinois.
13 Permission is granted to make and distribute verbatim copies of this
14 manual provided the copyright notice and this permission notice are
15 preserved on all copies.
17 Permission is granted to copy and distribute modified versions of
18 this manual under the conditions for verbatim copying, provided that the
19 entire resulting derived work is distributed under the terms of a
20 permission notice identical to this one.
22 Permission is granted to copy and distribute translations of this
23 manual into another language, under the above conditions for modified
24 versions, except that this permission notice may be stated in a
25 translation approved by the Foundation.
27 Permission is granted to copy and distribute modified versions of
28 this manual under the conditions for verbatim copying, provided also
29 that the section entitled "GNU General Public License" is included
30 exactly as in the original, and provided that the entire resulting
31 derived work is distributed under the terms of a permission notice
32 identical to this one.
34 Permission is granted to copy and distribute translations of this
35 manual into another language, under the above conditions for modified
36 versions, except that the section entitled "GNU General Public License"
37 may be included in a translation approved by the Free Software
38 Foundation instead of in the original English.
41 File: internals.info, Node: Lstream Functions, Next: Lstream Methods, Prev: Lstream Types, Up: Lstreams
46 - Function: Lstream * Lstream_new (Lstream_implementation *IMP, const
48 Allocate and return a new Lstream. This function is not really
49 meant to be called directly; rather, each stream type should
50 provide its own stream creation function, which creates the stream
51 and does any other necessary creation stuff (e.g. opening a file).
53 - Function: void Lstream_set_buffering (Lstream *LSTR,
54 Lstream_buffering BUFFERING, int BUFFERING_SIZE)
55 Change the buffering of a stream. See `lstream.h'. By default the
56 buffering is `STREAM_BLOCK_BUFFERED'.
58 - Function: int Lstream_flush (Lstream *LSTR)
59 Flush out any pending unwritten data in the stream. Clear any
60 buffered input data. Returns 0 on success, -1 on error.
62 - Macro: int Lstream_putc (Lstream *STREAM, int C)
63 Write out one byte to the stream. This is a macro and so it is
64 very efficient. The C argument is only evaluated once but the
65 STREAM argument is evaluated more than once. Returns 0 on
68 - Macro: int Lstream_getc (Lstream *STREAM)
69 Read one byte from the stream. This is a macro and so it is very
70 efficient. The STREAM argument is evaluated more than once.
71 Return value is -1 for EOF or error.
73 - Macro: void Lstream_ungetc (Lstream *STREAM, int C)
74 Push one byte back onto the input queue. This will be the next
75 byte read from the stream. Any number of bytes can be pushed back
76 and will be read in the reverse order they were pushed back--most
77 recent first. (This is necessary for consistency--if there are a
78 number of bytes that have been unread and I read and unread a
79 byte, it needs to be the first to be read again.) This is a macro
80 and so it is very efficient. The C argument is only evaluated
81 once but the STREAM argument is evaluated more than once.
83 - Function: int Lstream_fputc (Lstream *STREAM, int C)
84 - Function: int Lstream_fgetc (Lstream *STREAM)
85 - Function: void Lstream_fungetc (Lstream *STREAM, int C)
86 Function equivalents of the above macros.
88 - Function: ssize_t Lstream_read (Lstream *STREAM, void *DATA, size_t
90 Read SIZE bytes of DATA from the stream. Return the number of
91 bytes read. 0 means EOF. -1 means an error occurred and no bytes
94 - Function: ssize_t Lstream_write (Lstream *STREAM, void *DATA, size_t
96 Write SIZE bytes of DATA to the stream. Return the number of
97 bytes written. -1 means an error occurred and no bytes were
100 - Function: void Lstream_unread (Lstream *STREAM, void *DATA, size_t
102 Push back SIZE bytes of DATA onto the input queue. The next call
103 to `Lstream_read()' with the same size will read the same bytes
104 back. Note that this will be the case even if there is other
107 - Function: int Lstream_close (Lstream *STREAM)
108 Close the stream. All data will be flushed out.
110 - Function: void Lstream_reopen (Lstream *STREAM)
111 Reopen a closed stream. This enables I/O on it again. This is not
112 meant to be called except from a wrapper routine that reinitializes
113 variables and such--the close routine may well have freed some
114 necessary storage structures, for example.
116 - Function: void Lstream_rewind (Lstream *STREAM)
117 Rewind the stream to the beginning.
120 File: internals.info, Node: Lstream Methods, Prev: Lstream Functions, Up: Lstreams
125 - Lstream Method: ssize_t reader (Lstream *STREAM, unsigned char
127 Read some data from the stream's end and store it into DATA, which
128 can hold SIZE bytes. Return the number of bytes read. A return
129 value of 0 means no bytes can be read at this time. This may be
130 because of an EOF, or because there is a granularity greater than
131 one byte that the stream imposes on the returned data, and SIZE is
132 less than this granularity. (This will happen frequently for
133 streams that need to return whole characters, because
134 `Lstream_read()' calls the reader function repeatedly until it has
135 the number of bytes it wants or until 0 is returned.) The lstream
136 functions do not treat a 0 return as EOF or do anything special;
137 however, the calling function will interpret any 0 it gets back as
138 EOF. This will normally not happen unless the caller calls
139 `Lstream_read()' with a very small size.
141 This function can be `NULL' if the stream is output-only.
143 - Lstream Method: ssize_t writer (Lstream *STREAM, const unsigned char
145 Send some data to the stream's end. Data to be sent is in DATA
146 and is SIZE bytes. Return the number of bytes sent. This
147 function can send and return fewer bytes than is passed in; in that
148 case, the function will just be called again until there is no
149 data left or 0 is returned. A return value of 0 means that no
150 more data can be currently stored, but there is no error; the data
151 will be squirreled away until the writer can accept data. (This is
152 useful, e.g., if you're dealing with a non-blocking file
153 descriptor and are getting `EWOULDBLOCK' errors.) This function
154 can be `NULL' if the stream is input-only.
156 - Lstream Method: int rewinder (Lstream *STREAM)
157 Rewind the stream. If this is `NULL', the stream is not seekable.
159 - Lstream Method: int seekable_p (Lstream *STREAM)
160 Indicate whether this stream is seekable--i.e. it can be rewound.
161 This method is ignored if the stream does not have a rewind
162 method. If this method is not present, the result is determined
163 by whether a rewind method is present.
165 - Lstream Method: int flusher (Lstream *STREAM)
166 Perform any additional operations necessary to flush the data in
169 - Lstream Method: int pseudo_closer (Lstream *STREAM)
171 - Lstream Method: int closer (Lstream *STREAM)
172 Perform any additional operations necessary to close this stream
173 down. May be `NULL'. This function is called when
174 `Lstream_close()' is called or when the stream is
175 garbage-collected. When this function is called, all pending data
176 in the stream will already have been written out.
178 - Lstream Method: Lisp_Object marker (Lisp_Object LSTREAM, void
179 (*MARKFUN) (Lisp_Object))
180 Mark this object for garbage collection. Same semantics as a
181 standard `Lisp_Object' marker. This function can be `NULL'.
184 File: internals.info, Node: Consoles; Devices; Frames; Windows, Next: The Redisplay Mechanism, Prev: Lstreams, Up: Top
186 Consoles; Devices; Frames; Windows
187 **********************************
191 * Introduction to Consoles; Devices; Frames; Windows::
194 * The Window Object::
197 File: internals.info, Node: Introduction to Consoles; Devices; Frames; Windows, Next: Point, Up: Consoles; Devices; Frames; Windows
199 Introduction to Consoles; Devices; Frames; Windows
200 ==================================================
202 A window-system window that you see on the screen is called a
203 "frame" in Emacs terminology. Each frame is subdivided into one or
204 more non-overlapping panes, called (confusingly) "windows". Each
205 window displays the text of a buffer in it. (See above on Buffers.) Note
206 that buffers and windows are independent entities: Two or more windows
207 can be displaying the same buffer (potentially in different locations),
208 and a buffer can be displayed in no windows.
210 A single display screen that contains one or more frames is called a
211 "display". Under most circumstances, there is only one display.
212 However, more than one display can exist, for example if you have a
213 "multi-headed" console, i.e. one with a single keyboard but multiple
214 displays. (Typically in such a situation, the various displays act like
215 one large display, in that the mouse is only in one of them at a time,
216 and moving the mouse off of one moves it into another.) In some cases,
217 the different displays will have different characteristics, e.g. one
220 XEmacs can display frames on multiple displays. It can even deal
221 simultaneously with frames on multiple keyboards (called "consoles" in
222 XEmacs terminology). Here is one case where this might be useful: You
223 are using XEmacs on your workstation at work, and leave it running.
224 Then you go home and dial in on a TTY line, and you can use the
225 already-running XEmacs process to display another frame on your local
228 Thus, there is a hierarchy console -> display -> frame -> window.
229 There is a separate Lisp object type for each of these four concepts.
230 Furthermore, there is logically a "selected console", "selected
231 display", "selected frame", and "selected window". Each of these
232 objects is distinguished in various ways, such as being the default
233 object for various functions that act on objects of that type. Note
234 that every containing object remembers the "selected" object among the
235 objects that it contains: e.g. not only is there a selected window, but
236 every frame remembers the last window in it that was selected, and
237 changing the selected frame causes the remembered window within it to
238 become the selected window. Similar relationships apply for consoles
239 to devices and devices to frames.
242 File: internals.info, Node: Point, Next: Window Hierarchy, Prev: Introduction to Consoles; Devices; Frames; Windows, Up: Consoles; Devices; Frames; Windows
247 Recall that every buffer has a current insertion position, called
248 "point". Now, two or more windows may be displaying the same buffer,
249 and the text cursor in the two windows (i.e. `point') can be in two
250 different places. You may ask, how can that be, since each buffer has
251 only one value of `point'? The answer is that each window also has a
252 value of `point' that is squirreled away in it. There is only one
253 selected window, and the value of "point" in that buffer corresponds to
254 that window. When the selected window is changed from one window to
255 another displaying the same buffer, the old value of `point' is stored
256 into the old window's "point" and the value of `point' from the new
257 window is retrieved and made the value of `point' in the buffer. This
258 means that `window-point' for the selected window is potentially
259 inaccurate, and if you want to retrieve the correct value of `point'
260 for a window, you must special-case on the selected window and retrieve
261 the buffer's point instead. This is related to why
262 `save-window-excursion' does not save the selected window's value of
266 File: internals.info, Node: Window Hierarchy, Next: The Window Object, Prev: Point, Up: Consoles; Devices; Frames; Windows
271 If a frame contains multiple windows (panes), they are always created
272 by splitting an existing window along the horizontal or vertical axis.
273 Terminology is a bit confusing here: to "split a window horizontally"
274 means to create two side-by-side windows, i.e. to make a _vertical_ cut
275 in a window. Likewise, to "split a window vertically" means to create
276 two windows, one above the other, by making a _horizontal_ cut.
278 If you split a window and then split again along the same axis, you
279 will end up with a number of panes all arranged along the same axis.
280 The precise way in which the splits were made should not be important,
281 and this is reflected internally. Internally, all windows are arranged
282 in a tree, consisting of two types of windows, "combination" windows
283 (which have children, and are covered completely by those children) and
284 "leaf" windows, which have no children and are visible. Every
285 combination window has two or more children, all arranged along the same
286 axis. There are (logically) two subtypes of windows, depending on
287 whether their children are horizontally or vertically arrayed. There is
288 always one root window, which is either a leaf window (if the frame
289 contains only one window) or a combination window (if the frame contains
290 more than one window). In the latter case, the root window will have
291 two or more children, either horizontally or vertically arrayed, and
292 each of those children will be either a leaf window or another
297 1. Horizontal combination windows can never have children that are
298 horizontal combination windows; same for vertical.
300 2. Only leaf windows can be split (obviously) and this splitting does
301 one of two things: (a) turns the leaf window into a combination
302 window and creates two new leaf children, or (b) turns the leaf
303 window into one of the two new leaves and creates the other leaf.
304 Rule (1) dictates which of these two outcomes happens.
306 3. Every combination window must have at least two children.
308 4. Leaf windows can never become combination windows. They can be
309 deleted, however. If this results in a violation of (3), the
310 parent combination window also gets deleted.
312 5. All functions that accept windows must be prepared to accept
313 combination windows, and do something sane (e.g. signal an error
314 if so). Combination windows _do_ escape to the Lisp level.
316 6. All windows have three fields governing their contents: these are
317 "hchild" (a list of horizontally-arrayed children), "vchild" (a
318 list of vertically-arrayed children), and "buffer" (the buffer
319 contained in a leaf window). Exactly one of these will be
320 non-`nil'. Remember that "horizontally-arrayed" means
321 "side-by-side" and "vertically-arrayed" means "one above the
324 7. Leaf windows also have markers in their `start' (the first buffer
325 position displayed in the window) and `pointm' (the window's
326 stashed value of `point'--see above) fields, while combination
327 windows have `nil' in these fields.
329 8. The list of children for a window is threaded through the `next'
330 and `prev' fields of each child window.
332 9. *Deleted windows can be undeleted*. This happens as a result of
333 restoring a window configuration, and is unlike frames, displays,
334 and consoles, which, once deleted, can never be restored.
335 Deleting a window does nothing except set a special `dead' bit to
336 1 and clear out the `next', `prev', `hchild', and `vchild' fields,
339 10. Most frames actually have two top-level windows--one for the
340 minibuffer and one (the "root") for everything else. The modeline
341 (if present) separates these two. The `next' field of the root
342 points to the minibuffer, and the `prev' field of the minibuffer
343 points to the root. The other `next' and `prev' fields are `nil',
344 and the frame points to both of these windows. Minibuffer-less
345 frames have no minibuffer window, and the `next' and `prev' of the
346 root window are `nil'. Minibuffer-only frames have no root
347 window, and the `next' of the minibuffer window is `nil' but the
348 `prev' points to itself. (#### This is an artifact that should be
352 File: internals.info, Node: The Window Object, Prev: Window Hierarchy, Up: Consoles; Devices; Frames; Windows
357 Windows have the following accessible fields:
360 The frame that this window is on.
363 Non-`nil' if this window is a minibuffer window.
366 The buffer that the window is displaying. This may change often
367 during the life of the window.
370 Non-`nil' if this window is dedicated to its buffer.
373 This is the value of point in the current buffer when this window
374 is selected; when it is not selected, it retains its previous
378 The position in the buffer that is the first character to be
379 displayed in the window.
382 If this flag is non-`nil', it says that the window has been
383 scrolled explicitly by the Lisp program. This affects what the
384 next redisplay does if point is off the screen: instead of
385 scrolling the window to show the text around point, it moves point
386 to a location that is on the screen.
389 The `modified' field of the window's buffer, as of the last time a
390 redisplay completed in this window.
393 The buffer's value of point, as of the last time a redisplay
394 completed in this window.
397 This is the left-hand edge of the window, measured in columns.
398 (The leftmost column on the screen is column 0.)
401 This is the top edge of the window, measured in lines. (The top
402 line on the screen is line 0.)
405 The height of the window, measured in lines.
408 The width of the window, measured in columns.
411 This is the window that is the next in the chain of siblings. It
412 is `nil' in a window that is the rightmost or bottommost of a
416 This is the window that is the previous in the chain of siblings.
417 It is `nil' in a window that is the leftmost or topmost of a group
421 Internally, XEmacs arranges windows in a tree; each group of
422 siblings has a parent window whose area includes all the siblings.
423 This field points to a window's parent.
425 Parent windows do not display buffers, and play little role in
426 display except to shape their child windows. Emacs Lisp programs
427 usually have no access to the parent windows; they operate on the
428 windows at the leaves of the tree, which actually display buffers.
431 This is the number of columns that the display in the window is
432 scrolled horizontally to the left. Normally, this is 0.
435 This is the last time that the window was selected. The function
436 `get-lru-window' uses this field.
439 The window's display table, or `nil' if none is specified for it.
442 Non-`nil' means this window's mode line needs to be updated.
445 The line number of a certain position in the buffer, or `nil'.
446 This is used for displaying the line number of point in the mode
450 The position in the buffer for which the line number is known, or
451 `nil' meaning none is known.
454 If the region (or part of it) is highlighted in this window, this
455 field holds the mark position that made one end of that region.
456 Otherwise, this field is `nil'.
459 File: internals.info, Node: The Redisplay Mechanism, Next: Extents, Prev: Consoles; Devices; Frames; Windows, Up: Top
461 The Redisplay Mechanism
462 ***********************
464 The redisplay mechanism is one of the most complicated sections of
465 XEmacs, especially from a conceptual standpoint. This is doubly so
466 because, unlike for the basic aspects of the Lisp interpreter, the
467 computer science theories of how to efficiently handle redisplay are not
470 When working with the redisplay mechanism, remember the Golden Rules
473 1. It Is Better To Be Correct Than Fast.
475 2. Thou Shalt Not Run Elisp From Within Redisplay.
477 3. It Is Better To Be Fast Than Not To Be.
481 * Critical Redisplay Sections::
483 * Redisplay Piece by Piece::
486 File: internals.info, Node: Critical Redisplay Sections, Next: Line Start Cache, Up: The Redisplay Mechanism
488 Critical Redisplay Sections
489 ===========================
491 Within this section, we are defenseless and assume that the
492 following cannot happen:
494 1. garbage collection
496 2. Lisp code evaluation
498 3. frame size changes
500 We ensure (3) by calling `hold_frame_size_changes()', which will
501 cause any pending frame size changes to get put on hold till after the
502 end of the critical section. (1) follows automatically if (2) is met.
503 #### Unfortunately, there are some places where Lisp code can be called
504 within this section. We need to remove them.
506 If `Fsignal()' is called during this critical section, we will
509 If garbage collection is called during this critical section, we
510 simply return. #### We should abort instead.
512 #### If a frame-size change does occur we should probably actually
513 be preempting redisplay.
516 File: internals.info, Node: Line Start Cache, Next: Redisplay Piece by Piece, Prev: Critical Redisplay Sections, Up: The Redisplay Mechanism
521 The traditional scrolling code in Emacs breaks in a variable height
522 world. It depends on the key assumption that the number of lines that
523 can be displayed at any given time is fixed. This led to a complete
524 separation of the scrolling code from the redisplay code. In order to
525 fully support variable height lines, the scrolling code must actually be
526 tightly integrated with redisplay. Only redisplay can determine how
527 many lines will be displayed on a screen for any given starting point.
529 What is ideally wanted is a complete list of the starting buffer
530 position for every possible display line of a buffer along with the
531 height of that display line. Maintaining such a full list would be very
532 expensive. We settle for having it include information for all areas
533 which we happen to generate anyhow (i.e. the region currently being
534 displayed) and for those areas we need to work with.
536 In order to ensure that the cache accurately represents what
537 redisplay would actually show, it is necessary to invalidate it in many
538 situations. If the buffer changes, the starting positions may no longer
539 be correct. If a face or an extent has changed then the line heights
540 may have altered. These events happen frequently enough that the cache
541 can end up being constantly disabled. With this potentially constant
542 invalidation when is the cache ever useful?
544 Even if the cache is invalidated before every single usage, it is
545 necessary. Scrolling often requires knowledge about display lines which
546 are actually above or below the visible region. The cache provides a
547 convenient light-weight method of storing this information for multiple
548 display regions. This knowledge is necessary for the scrolling code to
549 always obey the First Golden Rule of Redisplay.
551 If the cache already contains all of the information that the
552 scrolling routines happen to need so that it doesn't have to go
553 generate it, then we are able to obey the Third Golden Rule of
554 Redisplay. The first thing we do to help out the cache is to always
555 add the displayed region. This region had to be generated anyway, so
556 the cache ends up getting the information basically for free. In those
557 cases where a user is simply scrolling around viewing a buffer there is
558 a high probability that this is sufficient to always provide the needed
559 information. The second thing we can do is be smart about invalidating
562 TODO--Be smart about invalidating the cache. Potential places:
564 * Insertions at end-of-line which don't cause line-wraps do not
565 alter the starting positions of any display lines. These types of
566 buffer modifications should not invalidate the cache. This is
567 actually a large optimization for redisplay speed as well.
569 * Buffer modifications frequently only affect the display of lines
570 at and below where they occur. In these situations we should only
571 invalidate the part of the cache starting at where the
574 In case you're wondering, the Second Golden Rule of Redisplay is not
578 File: internals.info, Node: Redisplay Piece by Piece, Prev: Line Start Cache, Up: The Redisplay Mechanism
580 Redisplay Piece by Piece
581 ========================
583 As you can begin to see redisplay is complex and also not well
584 documented. Chuck no longer works on XEmacs so this section is my take
585 on the workings of redisplay.
587 Redisplay happens in three phases:
589 1. Determine desired display in area that needs redisplay.
590 Implemented by `redisplay.c'
592 2. Compare desired display with current display Implemented by
595 3. Output changes Implemented by `redisplay-output.c',
596 `redisplay-x.c', `redisplay-msw.c' and `redisplay-tty.c'
598 Steps 1 and 2 are device-independent and relatively complex. Step 3
599 is mostly device-dependent.
601 Determining the desired display
603 Display attributes are stored in `display_line' structures. Each
604 `display_line' consists of a set of `display_block''s and each
605 `display_block' contains a number of `rune''s. Generally dynarr's of
606 `display_line''s are held by each window representing the current
607 display and the desired display.
609 The `display_line' structures are tightly tied to buffers which
610 presents a problem for redisplay as this connection is bogus for the
611 modeline. Hence the `display_line' generation routines are duplicated
612 for generating the modeline. This means that the modeline display code
613 has many bugs that the standard redisplay code does not.
615 The guts of `display_line' generation are in `create_text_block',
616 which creates a single display line for the desired locale. This
617 incrementally parses the characters on the current line and generates
618 redisplay structures for each.
620 Gutter redisplay is different. Because the data to display is stored
621 in a string we cannot use `create_text_block'. Instead we use
622 `create_text_string_block' which performs the same function as
623 `create_text_block' but for strings. Many of the complexities of
624 `create_text_block' to do with cursor handling and selective display
628 File: internals.info, Node: Extents, Next: Faces, Prev: The Redisplay Mechanism, Up: Top
635 * Introduction to Extents:: Extents are ranges over text, with properties.
636 * Extent Ordering:: How extents are ordered internally.
637 * Format of the Extent Info:: The extent information in a buffer or string.
638 * Zero-Length Extents:: A weird special case.
639 * Mathematics of Extent Ordering:: A rigorous foundation.
640 * Extent Fragments:: Cached information useful for redisplay.
643 File: internals.info, Node: Introduction to Extents, Next: Extent Ordering, Up: Extents
645 Introduction to Extents
646 =======================
648 Extents are regions over a buffer, with a start and an end position
649 denoting the region of the buffer included in the extent. In addition,
650 either end can be closed or open, meaning that the endpoint is or is
651 not logically included in the extent. Insertion of a character at a
652 closed endpoint causes the character to go inside the extent; insertion
653 at an open endpoint causes the character to go outside.
655 Extent endpoints are stored using memory indices (see `insdel.c'),
656 to minimize the amount of adjusting that needs to be done when
657 characters are inserted or deleted.
659 (Formerly, extent endpoints at the gap could be either before or
660 after the gap, depending on the open/closedness of the endpoint. The
661 intent of this was to make it so that insertions would automatically go
662 inside or out of extents as necessary with no further work needing to
663 be done. It didn't work out that way, however, and just ended up
664 complexifying and buggifying all the rest of the code.)
667 File: internals.info, Node: Extent Ordering, Next: Format of the Extent Info, Prev: Introduction to Extents, Up: Extents
672 Extents are compared using memory indices. There are two orderings
673 for extents and both orders are kept current at all times. The normal
674 or "display" order is as follows:
676 Extent A is ``less than'' extent B,
677 that is, earlier in the display order,
678 if: A-start < B-start,
679 or if: A-start = B-start, and A-end > B-end
681 So if two extents begin at the same position, the larger of them is
682 the earlier one in the display order (`EXTENT_LESS' is true).
684 For the e-order, the same thing holds:
686 Extent A is ``less than'' extent B in e-order,
687 that is, later in the buffer,
689 or if: A-end = B-end, and A-start > B-start
691 So if two extents end at the same position, the smaller of them is
692 the earlier one in the e-order (`EXTENT_E_LESS' is true).
694 The display order and the e-order are complementary orders: any
695 theorem about the display order also applies to the e-order if you swap
696 all occurrences of "display order" and "e-order", "less than" and
697 "greater than", and "extent start" and "extent end".
700 File: internals.info, Node: Format of the Extent Info, Next: Zero-Length Extents, Prev: Extent Ordering, Up: Extents
702 Format of the Extent Info
703 =========================
705 An extent-info structure consists of a list of the buffer or string's
706 extents and a "stack of extents" that lists all of the extents over a
707 particular position. The stack-of-extents info is used for
708 optimization purposes--it basically caches some info that might be
709 expensive to compute. Certain otherwise hard computations are easy
710 given the stack of extents over a particular position, and if the stack
711 of extents over a nearby position is known (because it was calculated
712 at some prior point in time), it's easy to move the stack of extents to
715 Given that the stack of extents is an optimization, and given that
716 it requires memory, a string's stack of extents is wiped out each time
717 a garbage collection occurs. Therefore, any time you retrieve the
718 stack of extents, it might not be there. If you need it to be there,
719 use the `_force' version.
721 Similarly, a string may or may not have an extent_info structure.
722 (Generally it won't if there haven't been any extents added to the
723 string.) So use the `_force' version if you need the extent_info
724 structure to be there.
726 A list of extents is maintained as a double gap array: one gap array
727 is ordered by start index (the "display order") and the other is
728 ordered by end index (the "e-order"). Note that positions in an extent
729 list should logically be conceived of as referring _to_ a particular
730 extent (as is the norm in programs) rather than sitting between two
731 extents. Note also that callers of these functions should not be aware
732 of the fact that the extent list is implemented as an array, except for
733 the fact that positions are integers (this should be generalized to
734 handle integers and linked list equally well).
737 File: internals.info, Node: Zero-Length Extents, Next: Mathematics of Extent Ordering, Prev: Format of the Extent Info, Up: Extents
742 Extents can be zero-length, and will end up that way if their
743 endpoints are explicitly set that way or if their detachable property
744 is `nil' and all the text in the extent is deleted. (The exception is
745 open-open zero-length extents, which are barred from existing because
746 there is no sensible way to define their properties. Deletion of the
747 text in an open-open extent causes it to be converted into a closed-open
748 extent.) Zero-length extents are primarily used to represent
749 annotations, and behave as follows:
751 1. Insertion at the position of a zero-length extent expands the
752 extent if both endpoints are closed; goes after the extent if it
753 is closed-open; and goes before the extent if it is open-closed.
755 2. Deletion of a character on a side of a zero-length extent whose
756 corresponding endpoint is closed causes the extent to be detached
757 if it is detachable; if the extent is not detachable or the
758 corresponding endpoint is open, the extent remains in the buffer,
761 Note that closed-open, non-detachable zero-length extents behave
762 exactly like markers and that open-closed, non-detachable zero-length
763 extents behave like the "point-type" marker in Mule.
766 File: internals.info, Node: Mathematics of Extent Ordering, Next: Extent Fragments, Prev: Zero-Length Extents, Up: Extents
768 Mathematics of Extent Ordering
769 ==============================
771 The extents in a buffer are ordered by "display order" because that
772 is that order that the redisplay mechanism needs to process them in.
773 The e-order is an auxiliary ordering used to facilitate operations over
774 extents. The operations that can be performed on the ordered list of
775 extents in a buffer are
777 1. Locate where an extent would go if inserted into the list.
779 2. Insert an extent into the list.
781 3. Remove an extent from the list.
783 4. Map over all the extents that overlap a range.
785 (4) requires being able to determine the first and last extents that
788 NOTE: "overlap" is used as follows:
790 * two ranges overlap if they have at least one point in common.
791 Whether the endpoints are open or closed makes a difference here.
793 * a point overlaps a range if the point is contained within the
794 range; this is equivalent to treating a point P as the range [P,
797 * In the case of an _extent_ overlapping a point or range, the extent
798 is normally treated as having closed endpoints. This applies
799 consistently in the discussion of stacks of extents and such below.
800 Note that this definition of overlap is not necessarily consistent
801 with the extents that `map-extents' maps over, since `map-extents'
802 sometimes pays attention to whether the endpoints of an extents
803 are open or closed. But for our purposes, it greatly simplifies
804 things to treat all extents as having closed endpoints.
806 First, define >, <, <=, etc. as applied to extents to mean
807 comparison according to the display order. Comparison between an
808 extent E and an index I means comparison between E and the range [I, I].
810 Also define e>, e<, e<=, etc. to mean comparison according to the
813 For any range R, define R(0) to be the starting index of the range
814 and R(1) to be the ending index of the range.
816 For any extent E, define E(next) to be the extent directly following
817 E, and E(prev) to be the extent directly preceding E. Assume E(next)
818 and E(prev) can be determined from E in constant time. (This is
819 because we store the extent list as a doubly linked list.)
821 Similarly, define E(e-next) and E(e-prev) to be the extents directly
822 following and preceding E in the e-order.
826 Let R be a range. Let F be the first extent overlapping R. Let L
827 be the last extent overlapping R.
829 Theorem 1: R(1) lies between L and L(next), i.e. L <= R(1) < L(next).
831 This follows easily from the definition of display order. The basic
832 reason that this theorem applies is that the display order sorts by
833 increasing starting index.
835 Therefore, we can determine L just by looking at where we would
836 insert R(1) into the list, and if we know F and are moving forward over
837 extents, we can easily determine when we've hit L by comparing the
838 extent we're at to R(1).
840 Theorem 2: F(e-prev) e< [1, R(0)] e<= F.
842 This is the analog of Theorem 1, and applies because the e-order
843 sorts by increasing ending index.
845 Therefore, F can be found in the same amount of time as operation
846 (1), i.e. the time that it takes to locate where an extent would go if
847 inserted into the e-order list.
849 If the lists were stored as balanced binary trees, then operation (1)
850 would take logarithmic time, which is usually quite fast. However,
851 currently they're stored as simple doubly-linked lists, and instead we
852 do some caching to try to speed things up.
854 Define a "stack of extents" (or "SOE") as the set of extents
855 (ordered in the display order) that overlap an index I, together with
856 the SOE's "previous" extent, which is an extent that precedes I in the
857 e-order. (Hopefully there will not be very many extents between I and
858 the previous extent.)
862 Let I be an index, let S be the stack of extents on I, let F be the
863 first extent in S, and let P be S's previous extent.
865 Theorem 3: The first extent in S is the first extent that overlaps
868 Proof: Any extent that overlaps [I, J] but does not include I must
869 have a start index > I, and thus be greater than any extent in S.
871 Therefore, finding the first extent that overlaps a range R is the
872 same as finding the first extent that overlaps R(0).
874 Theorem 4: Let I2 be an index such that I2 > I, and let F2 be the
875 first extent that overlaps I2. Then, either F2 is in S or F2 is
876 greater than any extent in S.
878 Proof: If F2 does not include I then its start index is greater than
879 I and thus it is greater than any extent in S, including F. Otherwise,
880 F2 includes I and thus is in S, and thus F2 >= F.
883 File: internals.info, Node: Extent Fragments, Prev: Mathematics of Extent Ordering, Up: Extents
888 Imagine that the buffer is divided up into contiguous,
889 non-overlapping "runs" of text such that no extent starts or ends
890 within a run (extents that abut the run don't count).
892 An extent fragment is a structure that holds data about the run that
893 contains a particular buffer position (if the buffer position is at the
894 junction of two runs, the run after the position is used)--the
895 beginning and end of the run, a list of all of the extents in that run,
896 the "merged face" that results from merging all of the faces
897 corresponding to those extents, the begin and end glyphs at the
898 beginning of the run, etc. This is the information that redisplay needs
899 in order to display this run.
901 Extent fragments have to be very quick to update to a new buffer
902 position when moving linearly through the buffer. They rely on the
903 stack-of-extents code, which does the heavy-duty algorithmic work of
904 determining which extents overly a particular position.
907 File: internals.info, Node: Faces, Next: Glyphs, Prev: Extents, Up: Top
915 File: internals.info, Node: Glyphs, Next: Specifiers, Prev: Faces, Up: Top
920 Glyphs are graphical elements that can be displayed in XEmacs
921 buffers or gutters. We use the term graphical element here in the
922 broadest possible sense since glyphs can be as mundane as text or as
923 arcane as a native tab widget.
925 In XEmacs, glyphs represent the uninstantiated state of graphical
926 elements, i.e. they hold all the information necessary to produce an
927 image on-screen but the image need not exist at this stage, and multiple
928 screen images can be instantiated from a single glyph.
930 Glyphs are lazily instantiated by calling one of the glyph
931 functions. This usually occurs within redisplay when `Fglyph_height' is
932 called. Instantiation causes an image-instance to be created and
933 cached. This cache is on a per-device basis for all glyphs except
934 widget-glyphs, and on a per-window basis for widgets-glyphs. The
935 caching is done by `image_instantiate' and is necessary because it is
936 generally possible to display an image-instance in multiple domains.
937 For instance if we create a Pixmap, we can actually display this on
938 multiple windows - even though we only need a single Pixmap instance to
939 do this. If caching wasn't done then it would be necessary to create
940 image-instances for every displayable occurrence of a glyph - and every
941 usage - and this would be extremely memory and cpu intensive.
943 Widget-glyphs (a.k.a native widgets) are not cached in this way.
944 This is because widget-glyph image-instances on screen are toolkit
945 windows, and thus cannot be reused in multiple XEmacs domains. Thus
946 widget-glyphs are cached on an XEmacs window basis.
948 Any action on a glyph first consults the cache before actually
949 instantiating a widget.
954 Glyph instantiation is a hairy topic and requires some explanation.
955 The guts of glyph instantiation is contained within
956 `image_instantiate'. A glyph contains an image which is a specifier.
957 When a glyph function - for instance `Fglyph_height' - asks for a
958 property of the glyph that can only be determined from its instantiated
959 state, then the glyph image is instantiated and an image instance
960 created. The instantiation process is governed by the specifier code
961 and goes through a series of steps:
963 * Validation. Instantiation of image instances happens dynamically -
964 often within the guts of redisplay. Thus it is often not feasible
965 to catch instantiator errors at instantiation time. Instead the
966 instantiator is validated at the time it is added to the image
967 specifier. This function is defined by `image_validate' and at a
968 simple level validates keyword value pairs.
970 * Duplication. The specifier code by default takes a copy of the
971 instantiator. This is reasonable for most specifiers but in the
972 case of widget-glyphs can be problematic, since some of the
973 properties in the instantiator - for instance callbacks - could
974 cause infinite recursion in the copying process. Thus the image
975 code defines a function - `image_copy_instantiator' - which will
976 selectively copy values. This is controlled by the way that a
977 keyword is defined either using `IIFORMAT_VALID_KEYWORD' or
978 `IIFORMAT_VALID_NONCOPY_KEYWORD'. Note that the image caching and
979 redisplay code relies on instantiator copying to ensure that
980 current and new instantiators are actually different rather than
981 referring to the same thing.
983 * Normalization. Once the instantiator has been copied it must be
984 converted into a form that is viable at instantiation time. This
985 can involve no changes at all, but typically involves things like
986 converting file names to the actual data. This function is defined
987 by `image_going_to_add' and `normalize_image_instantiator'.
989 * Instantiation. When an image instance is actually required for
990 display it is instantiated using `image_instantiate'. This
991 involves calling instantiate methods that are specific to the type
992 of image being instantiated.
994 The final instantiation phase also involves a number of steps. In
995 order to understand these we need to describe a number of concepts.
997 An image is instantiated in a "domain", where a domain can be any
998 one of a device, frame, window or image-instance. The domain gives the
999 image-instance context and identity and properties that affect the
1000 appearance of the image-instance may be different for the same glyph
1001 instantiated in different domains. An example is the face used to
1002 display the image-instance.
1004 Although an image is instantiated in a particular domain the
1005 instantiation domain is not necessarily the domain in which the
1006 image-instance is cached. For example a pixmap can be instantiated in a
1007 window be actually be cached on a per-device basis. The domain in which
1008 the image-instance is actually cached is called the "governing-domain".
1009 A governing-domain is currently either a device or a window.
1010 Widget-glyphs and text-glyphs have a window as a governing-domain, all
1011 other image-instances have a device as the governing-domain. The
1012 governing domain for an image-instance is determined using the
1013 governing_domain image-instance method.
1018 Widget-Glyphs in the MS-Windows Environment
1019 ===========================================
1023 Widget-Glyphs in the X Environment
1024 ==================================
1026 Widget-glyphs under X make heavy use of lwlib (*note Lucid Widget
1027 Library::) for manipulating the native toolkit objects. This is
1028 primarily so that different toolkits can be supported for
1029 widget-glyphs, just as they are supported for features such as menubars
1032 Lwlib is extremely poorly documented and quite hairy so here is my
1033 understanding of what goes on.
1035 Lwlib maintains a set of widget_instances which mirror the
1036 hierarchical state of Xt widgets. I think this is so that widgets can
1037 be updated and manipulated generically by the lwlib library. For
1038 instance update_one_widget_instance can cope with multiple types of
1039 widget and multiple types of toolkit. Each element in the widget
1040 hierarchy is updated from its corresponding widget_instance by walking
1041 the widget_instance tree recursively.
1043 This has desirable properties such as lw_modify_all_widgets which is
1044 called from `glyphs-x.c' and updates all the properties of a widget
1045 without having to know what the widget is or what toolkit it is from.
1046 Unfortunately this also has hairy properties such as making the lwlib
1047 code quite complex. And of course lwlib has to know at some level what
1048 the widget is and how to set its properties.
1051 File: internals.info, Node: Specifiers, Next: Menus, Prev: Glyphs, Up: Top
1059 File: internals.info, Node: Menus, Next: Subprocesses, Prev: Specifiers, Up: Top
1064 A menu is set by setting the value of the variable `current-menubar'
1065 (which may be buffer-local) and then calling `set-menubar-dirty-flag'
1066 to signal a change. This will cause the menu to be redrawn at the next
1067 redisplay. The format of the data in `current-menubar' is described in
1070 Internally the data in current-menubar is parsed into a tree of
1071 `widget_value's' (defined in `lwlib.h'); this is accomplished by the
1072 recursive function `menu_item_descriptor_to_widget_value()', called by
1073 `compute_menubar_data()'. Such a tree is deallocated using
1074 `free_widget_value()'.
1076 `update_screen_menubars()' is one of the external entry points.
1077 This checks to see, for each screen, if that screen's menubar needs to
1078 be updated. This is the case if
1080 1. `set-menubar-dirty-flag' was called since the last redisplay.
1081 (This function sets the C variable menubar_has_changed.)
1083 2. The buffer displayed in the screen has changed.
1085 3. The screen has no menubar currently displayed.
1087 `set_screen_menubar()' is called for each such screen. This
1088 function calls `compute_menubar_data()' to create the tree of
1089 widget_value's, then calls `lw_create_widget()',
1090 `lw_modify_all_widgets()', and/or `lw_destroy_all_widgets()' to create
1091 the X-Toolkit widget associated with the menu.
1093 `update_psheets()', the other external entry point, actually changes
1094 the menus being displayed. It uses the widgets fixed by
1095 `update_screen_menubars()' and calls various X functions to ensure that
1096 the menus are displayed properly.
1098 The menubar widget is set up so that `pre_activate_callback()' is
1099 called when the menu is first selected (i.e. mouse button goes down),
1100 and `menubar_selection_callback()' is called when an item is selected.
1101 `pre_activate_callback()' calls the function in activate-menubar-hook,
1102 which can change the menubar (this is described in `menubar.c'). If
1103 the menubar is changed, `set_screen_menubars()' is called.
1104 `menubar_selection_callback()' enqueues a menu event, putting in it a
1105 function to call (either `eval' or `call-interactively') and its
1106 argument, which is the callback function or form given in the menu's
1110 File: internals.info, Node: Subprocesses, Next: Interface to the X Window System, Prev: Menus, Up: Top
1115 The fields of a process are:
1118 A string, the name of the process.
1121 A list containing the command arguments that were used to start
1125 A function used to accept output from the process instead of a
1129 A function called whenever the process receives a signal, or `nil'.
1132 The associated buffer of the process.
1135 An integer, the Unix process ID.
1138 A flag, non-`nil' if this is really a child process. It is `nil'
1139 for a network connection.
1142 A marker indicating the position of the end of the last output
1143 from this process inserted into the buffer. This is often but not
1144 always the end of the buffer.
1146 `kill_without_query'
1147 If this is non-`nil', killing XEmacs while this process is still
1148 running does not ask for confirmation about killing the process.
1152 These two fields record 16 bits each of the process status
1153 returned by the `wait' system call.
1156 The process status, as `process-status' should return it.
1160 If these two fields are not equal, a change in the status of the
1161 process needs to be reported, either by running the sentinel or by
1162 inserting a message in the process buffer.
1165 Non-`nil' if communication with the subprocess uses a PTY; `nil'
1169 The file descriptor for input from the process.
1172 The file descriptor for output to the process.
1175 The file descriptor for the terminal that the subprocess is using.
1176 (On some systems, there is no need to record this, so the value is
1180 The name of the terminal that the subprocess is using, or `nil' if
1184 File: internals.info, Node: Interface to the X Window System, Next: Index, Prev: Subprocesses, Up: Top
1186 Interface to the X Window System
1187 ********************************
1189 Mostly undocumented.
1193 * Lucid Widget Library:: An interface to various widget sets.