1 This is ../info/internals.info, produced by makeinfo version 4.0b 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: Window Hierarchy, Next: The Window Object, Prev: Point, Up: Consoles; Devices; Frames; Windows
46 If a frame contains multiple windows (panes), they are always created
47 by splitting an existing window along the horizontal or vertical axis.
48 Terminology is a bit confusing here: to "split a window horizontally"
49 means to create two side-by-side windows, i.e. to make a _vertical_ cut
50 in a window. Likewise, to "split a window vertically" means to create
51 two windows, one above the other, by making a _horizontal_ cut.
53 If you split a window and then split again along the same axis, you
54 will end up with a number of panes all arranged along the same axis.
55 The precise way in which the splits were made should not be important,
56 and this is reflected internally. Internally, all windows are arranged
57 in a tree, consisting of two types of windows, "combination" windows
58 (which have children, and are covered completely by those children) and
59 "leaf" windows, which have no children and are visible. Every
60 combination window has two or more children, all arranged along the same
61 axis. There are (logically) two subtypes of windows, depending on
62 whether their children are horizontally or vertically arrayed. There is
63 always one root window, which is either a leaf window (if the frame
64 contains only one window) or a combination window (if the frame contains
65 more than one window). In the latter case, the root window will have
66 two or more children, either horizontally or vertically arrayed, and
67 each of those children will be either a leaf window or another
72 1. Horizontal combination windows can never have children that are
73 horizontal combination windows; same for vertical.
75 2. Only leaf windows can be split (obviously) and this splitting does
76 one of two things: (a) turns the leaf window into a combination
77 window and creates two new leaf children, or (b) turns the leaf
78 window into one of the two new leaves and creates the other leaf.
79 Rule (1) dictates which of these two outcomes happens.
81 3. Every combination window must have at least two children.
83 4. Leaf windows can never become combination windows. They can be
84 deleted, however. If this results in a violation of (3), the
85 parent combination window also gets deleted.
87 5. All functions that accept windows must be prepared to accept
88 combination windows, and do something sane (e.g. signal an error
89 if so). Combination windows _do_ escape to the Lisp level.
91 6. All windows have three fields governing their contents: these are
92 "hchild" (a list of horizontally-arrayed children), "vchild" (a
93 list of vertically-arrayed children), and "buffer" (the buffer
94 contained in a leaf window). Exactly one of these will be
95 non-`nil'. Remember that "horizontally-arrayed" means
96 "side-by-side" and "vertically-arrayed" means "one above the
99 7. Leaf windows also have markers in their `start' (the first buffer
100 position displayed in the window) and `pointm' (the window's
101 stashed value of `point'--see above) fields, while combination
102 windows have `nil' in these fields.
104 8. The list of children for a window is threaded through the `next'
105 and `prev' fields of each child window.
107 9. *Deleted windows can be undeleted*. This happens as a result of
108 restoring a window configuration, and is unlike frames, displays,
109 and consoles, which, once deleted, can never be restored.
110 Deleting a window does nothing except set a special `dead' bit to
111 1 and clear out the `next', `prev', `hchild', and `vchild' fields,
114 10. Most frames actually have two top-level windows--one for the
115 minibuffer and one (the "root") for everything else. The modeline
116 (if present) separates these two. The `next' field of the root
117 points to the minibuffer, and the `prev' field of the minibuffer
118 points to the root. The other `next' and `prev' fields are `nil',
119 and the frame points to both of these windows. Minibuffer-less
120 frames have no minibuffer window, and the `next' and `prev' of the
121 root window are `nil'. Minibuffer-only frames have no root
122 window, and the `next' of the minibuffer window is `nil' but the
123 `prev' points to itself. (#### This is an artifact that should be
127 File: internals.info, Node: The Window Object, Prev: Window Hierarchy, Up: Consoles; Devices; Frames; Windows
132 Windows have the following accessible fields:
135 The frame that this window is on.
138 Non-`nil' if this window is a minibuffer window.
141 The buffer that the window is displaying. This may change often
142 during the life of the window.
145 Non-`nil' if this window is dedicated to its buffer.
148 This is the value of point in the current buffer when this window
149 is selected; when it is not selected, it retains its previous
153 The position in the buffer that is the first character to be
154 displayed in the window.
157 If this flag is non-`nil', it says that the window has been
158 scrolled explicitly by the Lisp program. This affects what the
159 next redisplay does if point is off the screen: instead of
160 scrolling the window to show the text around point, it moves point
161 to a location that is on the screen.
164 The `modified' field of the window's buffer, as of the last time a
165 redisplay completed in this window.
168 The buffer's value of point, as of the last time a redisplay
169 completed in this window.
172 This is the left-hand edge of the window, measured in columns.
173 (The leftmost column on the screen is column 0.)
176 This is the top edge of the window, measured in lines. (The top
177 line on the screen is line 0.)
180 The height of the window, measured in lines.
183 The width of the window, measured in columns.
186 This is the window that is the next in the chain of siblings. It
187 is `nil' in a window that is the rightmost or bottommost of a
191 This is the window that is the previous in the chain of siblings.
192 It is `nil' in a window that is the leftmost or topmost of a group
196 Internally, XEmacs arranges windows in a tree; each group of
197 siblings has a parent window whose area includes all the siblings.
198 This field points to a window's parent.
200 Parent windows do not display buffers, and play little role in
201 display except to shape their child windows. Emacs Lisp programs
202 usually have no access to the parent windows; they operate on the
203 windows at the leaves of the tree, which actually display buffers.
206 This is the number of columns that the display in the window is
207 scrolled horizontally to the left. Normally, this is 0.
210 This is the last time that the window was selected. The function
211 `get-lru-window' uses this field.
214 The window's display table, or `nil' if none is specified for it.
217 Non-`nil' means this window's mode line needs to be updated.
220 The line number of a certain position in the buffer, or `nil'.
221 This is used for displaying the line number of point in the mode
225 The position in the buffer for which the line number is known, or
226 `nil' meaning none is known.
229 If the region (or part of it) is highlighted in this window, this
230 field holds the mark position that made one end of that region.
231 Otherwise, this field is `nil'.
234 File: internals.info, Node: The Redisplay Mechanism, Next: Extents, Prev: Consoles; Devices; Frames; Windows, Up: Top
236 The Redisplay Mechanism
237 ***********************
239 The redisplay mechanism is one of the most complicated sections of
240 XEmacs, especially from a conceptual standpoint. This is doubly so
241 because, unlike for the basic aspects of the Lisp interpreter, the
242 computer science theories of how to efficiently handle redisplay are not
245 When working with the redisplay mechanism, remember the Golden Rules
248 1. It Is Better To Be Correct Than Fast.
250 2. Thou Shalt Not Run Elisp From Within Redisplay.
252 3. It Is Better To Be Fast Than Not To Be.
256 * Critical Redisplay Sections::
258 * Redisplay Piece by Piece::
261 File: internals.info, Node: Critical Redisplay Sections, Next: Line Start Cache, Prev: The Redisplay Mechanism, Up: The Redisplay Mechanism
263 Critical Redisplay Sections
264 ===========================
266 Within this section, we are defenseless and assume that the
267 following cannot happen:
269 1. garbage collection
271 2. Lisp code evaluation
273 3. frame size changes
275 We ensure (3) by calling `hold_frame_size_changes()', which will
276 cause any pending frame size changes to get put on hold till after the
277 end of the critical section. (1) follows automatically if (2) is met.
278 #### Unfortunately, there are some places where Lisp code can be called
279 within this section. We need to remove them.
281 If `Fsignal()' is called during this critical section, we will
284 If garbage collection is called during this critical section, we
285 simply return. #### We should abort instead.
287 #### If a frame-size change does occur we should probably actually
288 be preempting redisplay.
291 File: internals.info, Node: Line Start Cache, Next: Redisplay Piece by Piece, Prev: Critical Redisplay Sections, Up: The Redisplay Mechanism
296 The traditional scrolling code in Emacs breaks in a variable height
297 world. It depends on the key assumption that the number of lines that
298 can be displayed at any given time is fixed. This led to a complete
299 separation of the scrolling code from the redisplay code. In order to
300 fully support variable height lines, the scrolling code must actually be
301 tightly integrated with redisplay. Only redisplay can determine how
302 many lines will be displayed on a screen for any given starting point.
304 What is ideally wanted is a complete list of the starting buffer
305 position for every possible display line of a buffer along with the
306 height of that display line. Maintaining such a full list would be very
307 expensive. We settle for having it include information for all areas
308 which we happen to generate anyhow (i.e. the region currently being
309 displayed) and for those areas we need to work with.
311 In order to ensure that the cache accurately represents what
312 redisplay would actually show, it is necessary to invalidate it in many
313 situations. If the buffer changes, the starting positions may no longer
314 be correct. If a face or an extent has changed then the line heights
315 may have altered. These events happen frequently enough that the cache
316 can end up being constantly disabled. With this potentially constant
317 invalidation when is the cache ever useful?
319 Even if the cache is invalidated before every single usage, it is
320 necessary. Scrolling often requires knowledge about display lines which
321 are actually above or below the visible region. The cache provides a
322 convenient light-weight method of storing this information for multiple
323 display regions. This knowledge is necessary for the scrolling code to
324 always obey the First Golden Rule of Redisplay.
326 If the cache already contains all of the information that the
327 scrolling routines happen to need so that it doesn't have to go
328 generate it, then we are able to obey the Third Golden Rule of
329 Redisplay. The first thing we do to help out the cache is to always
330 add the displayed region. This region had to be generated anyway, so
331 the cache ends up getting the information basically for free. In those
332 cases where a user is simply scrolling around viewing a buffer there is
333 a high probability that this is sufficient to always provide the needed
334 information. The second thing we can do is be smart about invalidating
337 TODO--Be smart about invalidating the cache. Potential places:
339 * Insertions at end-of-line which don't cause line-wraps do not
340 alter the starting positions of any display lines. These types of
341 buffer modifications should not invalidate the cache. This is
342 actually a large optimization for redisplay speed as well.
344 * Buffer modifications frequently only affect the display of lines
345 at and below where they occur. In these situations we should only
346 invalidate the part of the cache starting at where the
349 In case you're wondering, the Second Golden Rule of Redisplay is not
353 File: internals.info, Node: Redisplay Piece by Piece, Prev: Line Start Cache, Up: The Redisplay Mechanism
355 Redisplay Piece by Piece
356 ========================
358 As you can begin to see redisplay is complex and also not well
359 documented. Chuck no longer works on XEmacs so this section is my take
360 on the workings of redisplay.
362 Redisplay happens in three phases:
364 1. Determine desired display in area that needs redisplay.
365 Implemented by `redisplay.c'
367 2. Compare desired display with current display Implemented by
370 3. Output changes Implemented by `redisplay-output.c',
371 `redisplay-x.c', `redisplay-msw.c' and `redisplay-tty.c'
373 Steps 1 and 2 are device-independent and relatively complex. Step 3
374 is mostly device-dependent.
376 Determining the desired display
378 Display attributes are stored in `display_line' structures. Each
379 `display_line' consists of a set of `display_block''s and each
380 `display_block' contains a number of `rune''s. Generally dynarr's of
381 `display_line''s are held by each window representing the current
382 display and the desired display.
384 The `display_line' structures are tightly tied to buffers which
385 presents a problem for redisplay as this connection is bogus for the
386 modeline. Hence the `display_line' generation routines are duplicated
387 for generating the modeline. This means that the modeline display code
388 has many bugs that the standard redisplay code does not.
390 The guts of `display_line' generation are in `create_text_block',
391 which creates a single display line for the desired locale. This
392 incrementally parses the characters on the current line and generates
393 redisplay structures for each.
395 Gutter redisplay is different. Because the data to display is stored
396 in a string we cannot use `create_text_block'. Instead we use
397 `create_text_string_block' which performs the same function as
398 `create_text_block' but for strings. Many of the complexities of
399 `create_text_block' to do with cursor handling and selective display
403 File: internals.info, Node: Extents, Next: Faces, Prev: The Redisplay Mechanism, Up: Top
410 * Introduction to Extents:: Extents are ranges over text, with properties.
411 * Extent Ordering:: How extents are ordered internally.
412 * Format of the Extent Info:: The extent information in a buffer or string.
413 * Zero-Length Extents:: A weird special case.
414 * Mathematics of Extent Ordering:: A rigorous foundation.
415 * Extent Fragments:: Cached information useful for redisplay.
418 File: internals.info, Node: Introduction to Extents, Next: Extent Ordering, Prev: Extents, Up: Extents
420 Introduction to Extents
421 =======================
423 Extents are regions over a buffer, with a start and an end position
424 denoting the region of the buffer included in the extent. In addition,
425 either end can be closed or open, meaning that the endpoint is or is
426 not logically included in the extent. Insertion of a character at a
427 closed endpoint causes the character to go inside the extent; insertion
428 at an open endpoint causes the character to go outside.
430 Extent endpoints are stored using memory indices (see `insdel.c'),
431 to minimize the amount of adjusting that needs to be done when
432 characters are inserted or deleted.
434 (Formerly, extent endpoints at the gap could be either before or
435 after the gap, depending on the open/closedness of the endpoint. The
436 intent of this was to make it so that insertions would automatically go
437 inside or out of extents as necessary with no further work needing to
438 be done. It didn't work out that way, however, and just ended up
439 complexifying and buggifying all the rest of the code.)
442 File: internals.info, Node: Extent Ordering, Next: Format of the Extent Info, Prev: Introduction to Extents, Up: Extents
447 Extents are compared using memory indices. There are two orderings
448 for extents and both orders are kept current at all times. The normal
449 or "display" order is as follows:
451 Extent A is ``less than'' extent B,
452 that is, earlier in the display order,
453 if: A-start < B-start,
454 or if: A-start = B-start, and A-end > B-end
456 So if two extents begin at the same position, the larger of them is
457 the earlier one in the display order (`EXTENT_LESS' is true).
459 For the e-order, the same thing holds:
461 Extent A is ``less than'' extent B in e-order,
462 that is, later in the buffer,
464 or if: A-end = B-end, and A-start > B-start
466 So if two extents end at the same position, the smaller of them is
467 the earlier one in the e-order (`EXTENT_E_LESS' is true).
469 The display order and the e-order are complementary orders: any
470 theorem about the display order also applies to the e-order if you swap
471 all occurrences of "display order" and "e-order", "less than" and
472 "greater than", and "extent start" and "extent end".
475 File: internals.info, Node: Format of the Extent Info, Next: Zero-Length Extents, Prev: Extent Ordering, Up: Extents
477 Format of the Extent Info
478 =========================
480 An extent-info structure consists of a list of the buffer or string's
481 extents and a "stack of extents" that lists all of the extents over a
482 particular position. The stack-of-extents info is used for
483 optimization purposes--it basically caches some info that might be
484 expensive to compute. Certain otherwise hard computations are easy
485 given the stack of extents over a particular position, and if the stack
486 of extents over a nearby position is known (because it was calculated
487 at some prior point in time), it's easy to move the stack of extents to
490 Given that the stack of extents is an optimization, and given that
491 it requires memory, a string's stack of extents is wiped out each time
492 a garbage collection occurs. Therefore, any time you retrieve the
493 stack of extents, it might not be there. If you need it to be there,
494 use the `_force' version.
496 Similarly, a string may or may not have an extent_info structure.
497 (Generally it won't if there haven't been any extents added to the
498 string.) So use the `_force' version if you need the extent_info
499 structure to be there.
501 A list of extents is maintained as a double gap array: one gap array
502 is ordered by start index (the "display order") and the other is
503 ordered by end index (the "e-order"). Note that positions in an extent
504 list should logically be conceived of as referring _to_ a particular
505 extent (as is the norm in programs) rather than sitting between two
506 extents. Note also that callers of these functions should not be aware
507 of the fact that the extent list is implemented as an array, except for
508 the fact that positions are integers (this should be generalized to
509 handle integers and linked list equally well).
512 File: internals.info, Node: Zero-Length Extents, Next: Mathematics of Extent Ordering, Prev: Format of the Extent Info, Up: Extents
517 Extents can be zero-length, and will end up that way if their
518 endpoints are explicitly set that way or if their detachable property
519 is `nil' and all the text in the extent is deleted. (The exception is
520 open-open zero-length extents, which are barred from existing because
521 there is no sensible way to define their properties. Deletion of the
522 text in an open-open extent causes it to be converted into a closed-open
523 extent.) Zero-length extents are primarily used to represent
524 annotations, and behave as follows:
526 1. Insertion at the position of a zero-length extent expands the
527 extent if both endpoints are closed; goes after the extent if it
528 is closed-open; and goes before the extent if it is open-closed.
530 2. Deletion of a character on a side of a zero-length extent whose
531 corresponding endpoint is closed causes the extent to be detached
532 if it is detachable; if the extent is not detachable or the
533 corresponding endpoint is open, the extent remains in the buffer,
536 Note that closed-open, non-detachable zero-length extents behave
537 exactly like markers and that open-closed, non-detachable zero-length
538 extents behave like the "point-type" marker in Mule.
541 File: internals.info, Node: Mathematics of Extent Ordering, Next: Extent Fragments, Prev: Zero-Length Extents, Up: Extents
543 Mathematics of Extent Ordering
544 ==============================
546 The extents in a buffer are ordered by "display order" because that
547 is that order that the redisplay mechanism needs to process them in.
548 The e-order is an auxiliary ordering used to facilitate operations over
549 extents. The operations that can be performed on the ordered list of
550 extents in a buffer are
552 1. Locate where an extent would go if inserted into the list.
554 2. Insert an extent into the list.
556 3. Remove an extent from the list.
558 4. Map over all the extents that overlap a range.
560 (4) requires being able to determine the first and last extents that
563 NOTE: "overlap" is used as follows:
565 * two ranges overlap if they have at least one point in common.
566 Whether the endpoints are open or closed makes a difference here.
568 * a point overlaps a range if the point is contained within the
569 range; this is equivalent to treating a point P as the range [P,
572 * In the case of an _extent_ overlapping a point or range, the extent
573 is normally treated as having closed endpoints. This applies
574 consistently in the discussion of stacks of extents and such below.
575 Note that this definition of overlap is not necessarily consistent
576 with the extents that `map-extents' maps over, since `map-extents'
577 sometimes pays attention to whether the endpoints of an extents
578 are open or closed. But for our purposes, it greatly simplifies
579 things to treat all extents as having closed endpoints.
581 First, define >, <, <=, etc. as applied to extents to mean
582 comparison according to the display order. Comparison between an
583 extent E and an index I means comparison between E and the range [I, I].
585 Also define e>, e<, e<=, etc. to mean comparison according to the
588 For any range R, define R(0) to be the starting index of the range
589 and R(1) to be the ending index of the range.
591 For any extent E, define E(next) to be the extent directly following
592 E, and E(prev) to be the extent directly preceding E. Assume E(next)
593 and E(prev) can be determined from E in constant time. (This is
594 because we store the extent list as a doubly linked list.)
596 Similarly, define E(e-next) and E(e-prev) to be the extents directly
597 following and preceding E in the e-order.
601 Let R be a range. Let F be the first extent overlapping R. Let L
602 be the last extent overlapping R.
604 Theorem 1: R(1) lies between L and L(next), i.e. L <= R(1) < L(next).
606 This follows easily from the definition of display order. The basic
607 reason that this theorem applies is that the display order sorts by
608 increasing starting index.
610 Therefore, we can determine L just by looking at where we would
611 insert R(1) into the list, and if we know F and are moving forward over
612 extents, we can easily determine when we've hit L by comparing the
613 extent we're at to R(1).
615 Theorem 2: F(e-prev) e< [1, R(0)] e<= F.
617 This is the analog of Theorem 1, and applies because the e-order
618 sorts by increasing ending index.
620 Therefore, F can be found in the same amount of time as operation
621 (1), i.e. the time that it takes to locate where an extent would go if
622 inserted into the e-order list.
624 If the lists were stored as balanced binary trees, then operation (1)
625 would take logarithmic time, which is usually quite fast. However,
626 currently they're stored as simple doubly-linked lists, and instead we
627 do some caching to try to speed things up.
629 Define a "stack of extents" (or "SOE") as the set of extents
630 (ordered in the display order) that overlap an index I, together with
631 the SOE's "previous" extent, which is an extent that precedes I in the
632 e-order. (Hopefully there will not be very many extents between I and
633 the previous extent.)
637 Let I be an index, let S be the stack of extents on I, let F be the
638 first extent in S, and let P be S's previous extent.
640 Theorem 3: The first extent in S is the first extent that overlaps
643 Proof: Any extent that overlaps [I, J] but does not include I must
644 have a start index > I, and thus be greater than any extent in S.
646 Therefore, finding the first extent that overlaps a range R is the
647 same as finding the first extent that overlaps R(0).
649 Theorem 4: Let I2 be an index such that I2 > I, and let F2 be the
650 first extent that overlaps I2. Then, either F2 is in S or F2 is
651 greater than any extent in S.
653 Proof: If F2 does not include I then its start index is greater than
654 I and thus it is greater than any extent in S, including F. Otherwise,
655 F2 includes I and thus is in S, and thus F2 >= F.
658 File: internals.info, Node: Extent Fragments, Prev: Mathematics of Extent Ordering, Up: Extents
663 Imagine that the buffer is divided up into contiguous,
664 non-overlapping "runs" of text such that no extent starts or ends
665 within a run (extents that abut the run don't count).
667 An extent fragment is a structure that holds data about the run that
668 contains a particular buffer position (if the buffer position is at the
669 junction of two runs, the run after the position is used)--the
670 beginning and end of the run, a list of all of the extents in that run,
671 the "merged face" that results from merging all of the faces
672 corresponding to those extents, the begin and end glyphs at the
673 beginning of the run, etc. This is the information that redisplay needs
674 in order to display this run.
676 Extent fragments have to be very quick to update to a new buffer
677 position when moving linearly through the buffer. They rely on the
678 stack-of-extents code, which does the heavy-duty algorithmic work of
679 determining which extents overly a particular position.
682 File: internals.info, Node: Faces, Next: Glyphs, Prev: Extents, Up: Top
690 File: internals.info, Node: Glyphs, Next: Specifiers, Prev: Faces, Up: Top
695 Glyphs are graphical elements that can be displayed in XEmacs
696 buffers or gutters. We use the term graphical element here in the
697 broadest possible sense since glyphs can be as mundane as text or as
698 arcane as a native tab widget.
700 In XEmacs, glyphs represent the uninstantiated state of graphical
701 elements, i.e. they hold all the information necessary to produce an
702 image on-screen but the image need not exist at this stage, and multiple
703 screen images can be instantiated from a single glyph.
705 Glyphs are lazily instantiated by calling one of the glyph
706 functions. This usually occurs within redisplay when `Fglyph_height' is
707 called. Instantiation causes an image-instance to be created and
708 cached. This cache is on a per-device basis for all glyphs except
709 widget-glyphs, and on a per-window basis for widgets-glyphs. The
710 caching is done by `image_instantiate' and is necessary because it is
711 generally possible to display an image-instance in multiple domains.
712 For instance if we create a Pixmap, we can actually display this on
713 multiple windows - even though we only need a single Pixmap instance to
714 do this. If caching wasn't done then it would be necessary to create
715 image-instances for every displayable occurrence of a glyph - and every
716 usage - and this would be extremely memory and cpu intensive.
718 Widget-glyphs (a.k.a native widgets) are not cached in this way.
719 This is because widget-glyph image-instances on screen are toolkit
720 windows, and thus cannot be reused in multiple XEmacs domains. Thus
721 widget-glyphs are cached on an XEmacs window basis.
723 Any action on a glyph first consults the cache before actually
724 instantiating a widget.
729 Glyph instantiation is a hairy topic and requires some explanation.
730 The guts of glyph instantiation is contained within
731 `image_instantiate'. A glyph contains an image which is a specifier.
732 When a glyph function - for instance `Fglyph_height' - asks for a
733 property of the glyph that can only be determined from its instantiated
734 state, then the glyph image is instantiated and an image instance
735 created. The instantiation process is governed by the specifier code
736 and goes through a series of steps:
738 * Validation. Instantiation of image instances happens dynamically -
739 often within the guts of redisplay. Thus it is often not feasible
740 to catch instantiator errors at instantiation time. Instead the
741 instantiator is validated at the time it is added to the image
742 specifier. This function is defined by `image_validate' and at a
743 simple level validates keyword value pairs.
745 * Duplication. The specifier code by default takes a copy of the
746 instantiator. This is reasonable for most specifiers but in the
747 case of widget-glyphs can be problematic, since some of the
748 properties in the instantiator - for instance callbacks - could
749 cause infinite recursion in the copying process. Thus the image
750 code defines a function - `image_copy_instantiator' - which will
751 selectively copy values. This is controlled by the way that a
752 keyword is defined either using `IIFORMAT_VALID_KEYWORD' or
753 `IIFORMAT_VALID_NONCOPY_KEYWORD'. Note that the image caching and
754 redisplay code relies on instantiator copying to ensure that
755 current and new instantiators are actually different rather than
756 referring to the same thing.
758 * Normalization. Once the instantiator has been copied it must be
759 converted into a form that is viable at instantiation time. This
760 can involve no changes at all, but typically involves things like
761 converting file names to the actual data. This function is defined
762 by `image_going_to_add' and `normalize_image_instantiator'.
764 * Instantiation. When an image instance is actually required for
765 display it is instantiated using `image_instantiate'. This
766 involves calling instantiate methods that are specific to the type
767 of image being instantiated.
769 The final instantiation phase also involves a number of steps. In
770 order to understand these we need to describe a number of concepts.
772 An image is instantiated in a "domain", where a domain can be any
773 one of a device, frame, window or image-instance. The domain gives the
774 image-instance context and identity and properties that affect the
775 appearance of the image-instance may be different for the same glyph
776 instantiated in different domains. An example is the face used to
777 display the image-instance.
779 Although an image is instantiated in a particular domain the
780 instantiation domain is not necessarily the domain in which the
781 image-instance is cached. For example a pixmap can be instantiated in a
782 window be actually be cached on a per-device basis. The domain in which
783 the image-instance is actually cached is called the "governing-domain".
784 A governing-domain is currently either a device or a window.
785 Widget-glyphs and text-glyphs have a window as a governing-domain, all
786 other image-instances have a device as the governing-domain. The
787 governing domain for an image-instance is determined using the
788 governing_domain image-instance method.
793 Widget-Glyphs in the MS-Windows Environment
794 ===========================================
798 Widget-Glyphs in the X Environment
799 ==================================
801 Widget-glyphs under X make heavy use of lwlib (*note Lucid Widget
802 Library::) for manipulating the native toolkit objects. This is
803 primarily so that different toolkits can be supported for
804 widget-glyphs, just as they are supported for features such as menubars
807 Lwlib is extremely poorly documented and quite hairy so here is my
808 understanding of what goes on.
810 Lwlib maintains a set of widget_instances which mirror the
811 hierarchical state of Xt widgets. I think this is so that widgets can
812 be updated and manipulated generically by the lwlib library. For
813 instance update_one_widget_instance can cope with multiple types of
814 widget and multiple types of toolkit. Each element in the widget
815 hierarchy is updated from its corresponding widget_instance by walking
816 the widget_instance tree recursively.
818 This has desirable properties such as lw_modify_all_widgets which is
819 called from `glyphs-x.c' and updates all the properties of a widget
820 without having to know what the widget is or what toolkit it is from.
821 Unfortunately this also has hairy properties such as making the lwlib
822 code quite complex. And of course lwlib has to know at some level what
823 the widget is and how to set its properties.
826 File: internals.info, Node: Specifiers, Next: Menus, Prev: Glyphs, Up: Top
834 File: internals.info, Node: Menus, Next: Subprocesses, Prev: Specifiers, Up: Top
839 A menu is set by setting the value of the variable `current-menubar'
840 (which may be buffer-local) and then calling `set-menubar-dirty-flag'
841 to signal a change. This will cause the menu to be redrawn at the next
842 redisplay. The format of the data in `current-menubar' is described in
845 Internally the data in current-menubar is parsed into a tree of
846 `widget_value's' (defined in `lwlib.h'); this is accomplished by the
847 recursive function `menu_item_descriptor_to_widget_value()', called by
848 `compute_menubar_data()'. Such a tree is deallocated using
849 `free_widget_value()'.
851 `update_screen_menubars()' is one of the external entry points.
852 This checks to see, for each screen, if that screen's menubar needs to
853 be updated. This is the case if
855 1. `set-menubar-dirty-flag' was called since the last redisplay.
856 (This function sets the C variable menubar_has_changed.)
858 2. The buffer displayed in the screen has changed.
860 3. The screen has no menubar currently displayed.
862 `set_screen_menubar()' is called for each such screen. This
863 function calls `compute_menubar_data()' to create the tree of
864 widget_value's, then calls `lw_create_widget()',
865 `lw_modify_all_widgets()', and/or `lw_destroy_all_widgets()' to create
866 the X-Toolkit widget associated with the menu.
868 `update_psheets()', the other external entry point, actually changes
869 the menus being displayed. It uses the widgets fixed by
870 `update_screen_menubars()' and calls various X functions to ensure that
871 the menus are displayed properly.
873 The menubar widget is set up so that `pre_activate_callback()' is
874 called when the menu is first selected (i.e. mouse button goes down),
875 and `menubar_selection_callback()' is called when an item is selected.
876 `pre_activate_callback()' calls the function in activate-menubar-hook,
877 which can change the menubar (this is described in `menubar.c'). If
878 the menubar is changed, `set_screen_menubars()' is called.
879 `menubar_selection_callback()' enqueues a menu event, putting in it a
880 function to call (either `eval' or `call-interactively') and its
881 argument, which is the callback function or form given in the menu's
885 File: internals.info, Node: Subprocesses, Next: Interface to the X Window System, Prev: Menus, Up: Top
890 The fields of a process are:
893 A string, the name of the process.
896 A list containing the command arguments that were used to start
900 A function used to accept output from the process instead of a
904 A function called whenever the process receives a signal, or `nil'.
907 The associated buffer of the process.
910 An integer, the Unix process ID.
913 A flag, non-`nil' if this is really a child process. It is `nil'
914 for a network connection.
917 A marker indicating the position of the end of the last output
918 from this process inserted into the buffer. This is often but not
919 always the end of the buffer.
922 If this is non-`nil', killing XEmacs while this process is still
923 running does not ask for confirmation about killing the process.
927 These two fields record 16 bits each of the process status
928 returned by the `wait' system call.
931 The process status, as `process-status' should return it.
935 If these two fields are not equal, a change in the status of the
936 process needs to be reported, either by running the sentinel or by
937 inserting a message in the process buffer.
940 Non-`nil' if communication with the subprocess uses a PTY; `nil'
944 The file descriptor for input from the process.
947 The file descriptor for output to the process.
950 The file descriptor for the terminal that the subprocess is using.
951 (On some systems, there is no need to record this, so the value is
955 The name of the terminal that the subprocess is using, or `nil' if
959 File: internals.info, Node: Interface to the X Window System, Next: Index, Prev: Subprocesses, Up: Top
961 Interface to the X Window System
962 ********************************
968 * Lucid Widget Library:: An interface to various widget sets.
971 File: internals.info, Node: Lucid Widget Library, Up: Interface to the X Window System
976 Lwlib is extremely poorly documented and quite hairy. The author(s)
977 blame that on X, Xt, and Motif, with some justice, but also sufficient
978 hypocrisy to avoid drawing the obvious conclusion about their own work.
980 The Lucid Widget Library is composed of two more or less independent
981 pieces. The first, as the name suggests, is a set of widgets. These
982 widgets are intended to resemble and improve on widgets provided in the
983 Motif toolkit but not in the Athena widgets, including menubars and
984 scrollbars. Recent additions by Andy Piper integrate some "modern"
985 widgets by Edward Falk, including checkboxes, radio buttons, progress
986 gauges, and index tab controls (aka notebooks).
988 The second piece of the Lucid widget library is a generic interface
989 to several toolkits for X (including Xt, the Athena widget set, and
990 Motif, as well as the Lucid widgets themselves) so that core XEmacs
991 code need not know which widget set has been used to build the
992 graphical user interface.
996 * Generic Widget Interface:: The lwlib generic widget interface.
999 * Checkboxes and Radio Buttons::
1004 File: internals.info, Node: Generic Widget Interface, Next: Scrollbars, Up: Lucid Widget Library
1006 Generic Widget Interface
1007 ------------------------
1009 In general in any toolkit a widget may be a composite object. In Xt,
1010 all widgets have an X window that they manage, but typically a complex
1011 widget will have widget children, each of which manages a subwindow of
1012 the parent widget's X window. These children may themselves be
1013 composite widgets. Thus a widget is actually a tree or hierarchy of
1016 For each toolkit widget, lwlib maintains a tree of `widget_values'
1017 which mirror the hierarchical state of Xt widgets (including Motif,
1018 Athena, 3D Athena, and Falk's widget sets). Each `widget_value' has
1019 `contents' member, which points to the head of a linked list of its
1020 children. The linked list of siblings is chained through the `next'
1021 member of `widget_value'.
1029 +-------+ next +-------+ next +-------+
1030 | child |----->| child |----->| child |
1031 +-------+ +-------+ +-------+
1035 +-------------+ next +-------------+
1036 | grand child |----->| grand child |
1037 +-------------+ +-------------+
1039 The `widget_value' hierarchy of a composite widget with two simple
1040 children and one composite child.
1042 The `widget_instance' structure maintains the inverse view of the
1043 tree. As for the `widget_value', siblings are chained through the
1044 `next' member. However, rather than naming children, the
1045 `widget_instance' tree links to parents.
1053 +-------+ next +-------+ next +-------+
1054 | child |----->| child |----->| child |
1055 +-------+ +-------+ +-------+
1059 +-------------+ next +-------------+
1060 | grand child |----->| grand child |
1061 +-------------+ +-------------+
1063 The `widget_value' hierarchy of a composite widget with two simple
1064 children and one composite child.
1066 This permits widgets derived from different toolkits to be updated
1067 and manipulated generically by the lwlib library. For instance
1068 `update_one_widget_instance' can cope with multiple types of widget and
1069 multiple types of toolkit. Each element in the widget hierarchy is
1070 updated from its corresponding `widget_value' by walking the
1071 `widget_value' tree. This has desirable properties. For example,
1072 `lw_modify_all_widgets' is called from `glyphs-x.c' and updates all the
1073 properties of a widget without having to know what the widget is or
1074 what toolkit it is from. Unfortunately this also has its hairy
1075 properties; the lwlib code quite complex. And of course lwlib has to
1076 know at some level what the widget is and how to set its properties.
1078 The `widget_instance' structure also contains a pointer to the root
1079 of its tree. Widget instances are further confi
1082 File: internals.info, Node: Scrollbars, Next: Menubars, Prev: Generic Widget Interface, Up: Lucid Widget Library
1088 File: internals.info, Node: Menubars, Next: Checkboxes and Radio Buttons, Prev: Scrollbars, Up: Lucid Widget Library
1094 File: internals.info, Node: Checkboxes and Radio Buttons, Next: Progress Bars, Prev: Menubars, Up: Lucid Widget Library
1096 Checkboxes and Radio Buttons
1097 ----------------------------
1100 File: internals.info, Node: Progress Bars, Next: Tab Controls, Prev: Checkboxes and Radio Buttons, Up: Lucid Widget Library
1106 File: internals.info, Node: Tab Controls, Prev: Progress Bars, Up: Lucid Widget Library