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: 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 to 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 does not exist at this stage.
704 Glyphs are lazily instantiated by calling one of the glyph
705 functions. This usually occurs within redisplay when `Fglyph_height' is
706 called. Instantiation causes an image-instance to be created and
707 cached. This cache is on a device basis for all glyphs except
708 glyph-widgets, and on a window basis for glyph widgets. The caching is
709 done by `image_instantiate' and is necessary because it is generally
710 possible to display an image-instance in multiple domains. For instance
711 if we create a Pixmap, we can actually display this on multiple windows
712 - even though we only need a single Pixmap instance to do this. If
713 caching wasn't done then it would be necessary to create
714 image-instances for every displayable occurrence of a glyph - and every
715 usage - and this would be extremely memory and cpu intensive.
717 Widget-glyphs (a.k.a native widgets) are not cached in this way.
718 This is because widget-glyph image-instances on screen are toolkit
719 windows, and thus cannot be reused in multiple XEmacs domains. Thus
720 widget-glyphs are cached on a window basis.
722 Any action on a glyph first consults the cache before actually
723 instantiating a widget.
725 Widget-Glyphs in the MS-Windows Environment
726 ===========================================
730 Widget-Glyphs in the X Environment
731 ==================================
733 Widget-glyphs under X make heavy use of lwlib for manipulating the
734 native toolkit objects. This is primarily so that different toolkits can
735 be supported for widget-glyphs, just as they are supported for features
736 such as menubars etc.
738 Lwlib is extremely poorly documented and quite hairy so here is my
739 understanding of what goes on.
741 Lwlib maintains a set of widget_instances which mirror the
742 hierarchical state of Xt widgets. I think this is so that widgets can
743 be updated and manipulated generically by the lwlib library. For
744 instance update_one_widget_instance can cope with multiple types of
745 widget and multiple types of toolkit. Each element in the widget
746 hierarchy is updated from its corresponding widget_instance by walking
747 the widget_instance tree recursively.
749 This has desirable properties such as lw_modify_all_widgets which is
750 called from `glyphs-x.c' and updates all the properties of a widget
751 without having to know what the widget is or what toolkit it is from.
752 Unfortunately this also has hairy properties such as making the lwlib
753 code quite complex. And of course lwlib has to know at some level what
754 the widget is and how to set its properties.
757 File: internals.info, Node: Specifiers, Next: Menus, Prev: Glyphs, Up: Top
765 File: internals.info, Node: Menus, Next: Subprocesses, Prev: Specifiers, Up: Top
770 A menu is set by setting the value of the variable `current-menubar'
771 (which may be buffer-local) and then calling `set-menubar-dirty-flag'
772 to signal a change. This will cause the menu to be redrawn at the next
773 redisplay. The format of the data in `current-menubar' is described in
776 Internally the data in current-menubar is parsed into a tree of
777 `widget_value's' (defined in `lwlib.h'); this is accomplished by the
778 recursive function `menu_item_descriptor_to_widget_value()', called by
779 `compute_menubar_data()'. Such a tree is deallocated using
780 `free_widget_value()'.
782 `update_screen_menubars()' is one of the external entry points.
783 This checks to see, for each screen, if that screen's menubar needs to
784 be updated. This is the case if
786 1. `set-menubar-dirty-flag' was called since the last redisplay.
787 (This function sets the C variable menubar_has_changed.)
789 2. The buffer displayed in the screen has changed.
791 3. The screen has no menubar currently displayed.
793 `set_screen_menubar()' is called for each such screen. This
794 function calls `compute_menubar_data()' to create the tree of
795 widget_value's, then calls `lw_create_widget()',
796 `lw_modify_all_widgets()', and/or `lw_destroy_all_widgets()' to create
797 the X-Toolkit widget associated with the menu.
799 `update_psheets()', the other external entry point, actually changes
800 the menus being displayed. It uses the widgets fixed by
801 `update_screen_menubars()' and calls various X functions to ensure that
802 the menus are displayed properly.
804 The menubar widget is set up so that `pre_activate_callback()' is
805 called when the menu is first selected (i.e. mouse button goes down),
806 and `menubar_selection_callback()' is called when an item is selected.
807 `pre_activate_callback()' calls the function in activate-menubar-hook,
808 which can change the menubar (this is described in `menubar.c'). If
809 the menubar is changed, `set_screen_menubars()' is called.
810 `menubar_selection_callback()' enqueues a menu event, putting in it a
811 function to call (either `eval' or `call-interactively') and its
812 argument, which is the callback function or form given in the menu's
816 File: internals.info, Node: Subprocesses, Next: Interface to X Windows, Prev: Menus, Up: Top
821 The fields of a process are:
824 A string, the name of the process.
827 A list containing the command arguments that were used to start
831 A function used to accept output from the process instead of a
835 A function called whenever the process receives a signal, or `nil'.
838 The associated buffer of the process.
841 An integer, the Unix process ID.
844 A flag, non-`nil' if this is really a child process. It is `nil'
845 for a network connection.
848 A marker indicating the position of the end of the last output
849 from this process inserted into the buffer. This is often but not
850 always the end of the buffer.
853 If this is non-`nil', killing XEmacs while this process is still
854 running does not ask for confirmation about killing the process.
858 These two fields record 16 bits each of the process status
859 returned by the `wait' system call.
862 The process status, as `process-status' should return it.
866 If these two fields are not equal, a change in the status of the
867 process needs to be reported, either by running the sentinel or by
868 inserting a message in the process buffer.
871 Non-`nil' if communication with the subprocess uses a PTY; `nil'
875 The file descriptor for input from the process.
878 The file descriptor for output to the process.
881 The file descriptor for the terminal that the subprocess is using.
882 (On some systems, there is no need to record this, so the value is
886 The name of the terminal that the subprocess is using, or `nil' if
890 File: internals.info, Node: Interface to X Windows, Next: Index, Prev: Subprocesses, Up: Top
892 Interface to X Windows
893 **********************
898 File: internals.info, Node: Index, Prev: Interface to X Windows, Up: Top
905 * Amdahl Corporation: XEmacs.
906 * Andreessen, Marc: XEmacs.
907 * asynchronous subprocesses: Modules for Interfacing with the Operating System.
908 * Baur, Steve: XEmacs.
909 * Benson, Eric: Lucid Emacs.
910 * bridge, playing: XEmacs From the Outside.
911 * Buchholz, Martin: XEmacs.
912 * Bufbyte: Character-Related Data Types.
913 * Bufpos: Character-Related Data Types.
914 * Bytecount: Character-Related Data Types.
915 * bytecount_to_charcount: Working With Character and Byte Positions.
916 * Bytind: Character-Related Data Types.
917 * C vs. Lisp: The Lisp Language.
918 * caller-protects (GCPRO rule): Writing Lisp Primitives.
919 * case table: Modules for Other Aspects of the Lisp Interpreter and Object System.
920 * Charcount: Character-Related Data Types.
921 * charcount_to_bytecount: Working With Character and Byte Positions.
922 * charptr_emchar: Working With Character and Byte Positions.
923 * charptr_n_addr: Working With Character and Byte Positions.
924 * closer: Lstream Methods.
925 * closure: The XEmacs Object System (Abstractly Speaking).
926 * Coding for Mule: Coding for Mule.
927 * Common Lisp: The Lisp Language.
928 * compact_string_chars: compact_string_chars.
929 * conservative garbage collection: GCPROing.
930 * copy-on-write: General Coding Rules.
931 * critical redisplay sections: Critical Redisplay Sections.
932 * DEC_CHARPTR: Working With Character and Byte Positions.
933 * Devin, Matthieu: Lucid Emacs.
934 * display order of extents: Mathematics of Extent Ordering.
935 * dynamic array: Low-Level Modules.
936 * dynamic scoping: The Lisp Language.
937 * dynamic types: The Lisp Language.
938 * Emchar: Character-Related Data Types.
939 * Energize: Lucid Emacs.
941 * Epoch: Lucid Emacs.
942 * Extbyte: Character-Related Data Types.
943 * Extcount: Character-Related Data Types.
944 * extent fragment: Extent Fragments.
945 * extent mathematics: Mathematics of Extent Ordering.
946 * extent ordering: Mathematics of Extent Ordering.
947 * extents, display order: Mathematics of Extent Ordering.
948 * external widget: Modules for Interfacing with X Windows.
949 * flusher: Lstream Methods.
950 * Free Software Foundation: A History of Emacs.
951 * FSF: A History of Emacs.
952 * FSF Emacs <1>: GNU Emacs 20.
953 * FSF Emacs: GNU Emacs 19.
954 * garbage collection: Garbage Collection.
955 * garbage collection protection: Writing Lisp Primitives.
956 * garbage collection step by step: Garbage Collection - Step by Step.
957 * garbage collection, conservative: GCPROing.
958 * garbage collection, invocation: Invocation.
959 * garbage_collect_1: garbage_collect_1.
960 * gc_sweep: gc_sweep.
961 * GNU Emacs 19: GNU Emacs 19.
962 * GNU Emacs 20: GNU Emacs 20.
963 * Gosling, James <1>: The Lisp Language.
964 * Gosling, James: Through Version 18.
965 * Great Usenet Renaming: Through Version 18.
966 * Hackers (Steven Levy): A History of Emacs.
967 * hierarchy of windows: Window Hierarchy.
968 * history of Emacs: A History of Emacs.
969 * Illinois, University of: XEmacs.
970 * INC_CHARPTR: Working With Character and Byte Positions.
971 * interactive: Modules for Standard Editing Operations.
972 * interning: The XEmacs Object System (Abstractly Speaking).
973 * ITS (Incompatible Timesharing System): A History of Emacs.
974 * Java: The Lisp Language.
975 * Java vs. Lisp: The Lisp Language.
976 * Jones, Kyle: XEmacs.
977 * Kaplan, Simon: XEmacs.
978 * Levy, Steven: A History of Emacs.
979 * line start cache: Line Start Cache.
980 * Lisp vs. C: The Lisp Language.
981 * Lisp vs. Java: The Lisp Language.
982 * lstream: Modules for Interfacing with the File System.
983 * Lstream_close: Lstream Functions.
984 * Lstream_fgetc: Lstream Functions.
985 * Lstream_flush: Lstream Functions.
986 * Lstream_fputc: Lstream Functions.
987 * Lstream_fungetc: Lstream Functions.
988 * Lstream_getc: Lstream Functions.
989 * Lstream_new: Lstream Functions.
990 * Lstream_putc: Lstream Functions.
991 * Lstream_read: Lstream Functions.
992 * Lstream_reopen: Lstream Functions.
993 * Lstream_rewind: Lstream Functions.
994 * Lstream_set_buffering: Lstream Functions.
995 * Lstream_ungetc: Lstream Functions.
996 * Lstream_unread: Lstream Functions.
997 * Lstream_write: Lstream Functions.
998 * Lucid Emacs: Lucid Emacs.
999 * Lucid Inc.: Lucid Emacs.
1000 * mark and sweep: Garbage Collection.
1001 * mark method <1>: lrecords.
1002 * mark method: Modules for Other Aspects of the Lisp Interpreter and Object System.
1003 * mark_object: mark_object.
1004 * marker: Lstream Methods.
1005 * mathematics of extents: Mathematics of Extent Ordering.
1006 * MAX_EMCHAR_LEN: Working With Character and Byte Positions.
1007 * merging attempts: XEmacs.
1008 * MIT: A History of Emacs.
1009 * Mlynarik, Richard: GNU Emacs 19.
1010 * MULE merged XEmacs appears: XEmacs.
1011 * NAS: Modules for Interfacing with the Operating System.
1012 * native sound: Modules for Interfacing with the Operating System.
1013 * network connections: Modules for Interfacing with the Operating System.
1014 * network sound: Modules for Interfacing with the Operating System.
1015 * Niksic, Hrvoje: XEmacs.
1016 * pane: Modules for the Basic Displayable Lisp Objects.
1017 * permanent objects: The XEmacs Object System (Abstractly Speaking).
1018 * pi, calculating: XEmacs From the Outside.
1019 * pseudo_closer: Lstream Methods.
1020 * read syntax: The XEmacs Object System (Abstractly Speaking).
1021 * read-eval-print: XEmacs From the Outside.
1022 * reader: Lstream Methods.
1023 * Redisplay Piece by Piece: Redisplay Piece by Piece.
1024 * relocating allocator: Low-Level Modules.
1025 * rename to XEmacs: XEmacs.
1026 * rewinder: Lstream Methods.
1027 * RMS: A History of Emacs.
1028 * scanner: Modules for Other Aspects of the Lisp Interpreter and Object System.
1029 * scoping, dynamic: The Lisp Language.
1030 * seekable_p: Lstream Methods.
1031 * selections: Modules for Interfacing with X Windows.
1032 * set_charptr_emchar: Working With Character and Byte Positions.
1033 * Sexton, Harlan: Lucid Emacs.
1034 * sound, native: Modules for Interfacing with the Operating System.
1035 * sound, network: Modules for Interfacing with the Operating System.
1036 * SPARCWorks: XEmacs.
1037 * Stallman, Richard: A History of Emacs.
1038 * subprocesses, asynchronous: Modules for Interfacing with the Operating System.
1039 * subprocesses, synchronous: Modules for Interfacing with the Operating System.
1040 * Sun Microsystems: XEmacs.
1041 * sweep_bit_vectors_1: sweep_bit_vectors_1.
1042 * sweep_lcrecords_1: sweep_lcrecords_1.
1043 * sweep_strings: sweep_strings.
1044 * synchronous subprocesses: Modules for Interfacing with the Operating System.
1045 * taxes, doing: XEmacs From the Outside.
1046 * TECO: A History of Emacs.
1047 * temporary objects: The XEmacs Object System (Abstractly Speaking).
1048 * Thompson, Chuck: XEmacs.
1049 * types, dynamic: The Lisp Language.
1050 * University of Illinois: XEmacs.
1051 * Win-Emacs: XEmacs.
1052 * window (in Emacs): Modules for the Basic Displayable Lisp Objects.
1053 * window hierarchy: Window Hierarchy.
1054 * window point internals: The Window Object.
1055 * Wing, Ben: XEmacs.
1056 * writer: Lstream Methods.
1058 * XEmacs goes it alone: XEmacs.
1059 * Zawinski, Jamie: Lucid Emacs.
projects / chise / xemacs-chise.git- / blob