X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=info%2Finternals.info-8;h=36c52e97c3b31a47c650e37aa6c05672e834cad2;hb=2779fcb5d524d6b7de5a6ef9ebfd6662433a4a07;hp=c35a30fdb392f0a306c6a1bc37b9b75f5498c49d;hpb=d8bd7eee3147c839d3c74d1823c139cd54867a75;p=chise%2Fxemacs-chise.git diff --git a/info/internals.info-8 b/info/internals.info-8 index c35a30f..36c52e9 100644 --- a/info/internals.info-8 +++ b/info/internals.info-8 @@ -1,4 +1,4 @@ -This is ../info/internals.info, produced by makeinfo version 4.0 from +This is ../info/internals.info, produced by makeinfo version 4.0b from internals/internals.texi. INFO-DIR-SECTION XEmacs Editor @@ -92,14 +92,14 @@ combination window. "hchild" (a list of horizontally-arrayed children), "vchild" (a list of vertically-arrayed children), and "buffer" (the buffer contained in a leaf window). Exactly one of these will be - non-nil. Remember that "horizontally-arrayed" means + non-`nil'. Remember that "horizontally-arrayed" means "side-by-side" and "vertically-arrayed" means "one above the other". 7. Leaf windows also have markers in their `start' (the first buffer position displayed in the window) and `pointm' (the window's stashed value of `point'--see above) fields, while combination - windows have nil in these fields. + windows have `nil' in these fields. 8. The list of children for a window is threaded through the `next' and `prev' fields of each child window. @@ -516,7 +516,7 @@ Zero-Length Extents Extents can be zero-length, and will end up that way if their endpoints are explicitly set that way or if their detachable property -is nil and all the text in the extent is deleted. (The exception is +is `nil' and all the text in the extent is deleted. (The exception is open-open zero-length extents, which are barred from existing because there is no sensible way to define their properties. Deletion of the text in an open-open extent causes it to be converted into a closed-open @@ -694,34 +694,102 @@ Glyphs Glyphs are graphical elements that can be displayed in XEmacs buffers or gutters. We use the term graphical element here in the -broadest possible sense since glyphs can be as mundane as text to as +broadest possible sense since glyphs can be as mundane as text or as arcane as a native tab widget. In XEmacs, glyphs represent the uninstantiated state of graphical elements, i.e. they hold all the information necessary to produce an -image on-screen but the image does not exist at this stage. +image on-screen but the image need not exist at this stage, and multiple +screen images can be instantiated from a single glyph. Glyphs are lazily instantiated by calling one of the glyph functions. This usually occurs within redisplay when `Fglyph_height' is called. Instantiation causes an image-instance to be created and -cached. This cache is on a device basis for all glyphs except -glyph-widgets, and on a window basis for glyph widgets. The caching is -done by `image_instantiate' and is necessary because it is generally -possible to display an image-instance in multiple domains. For instance -if we create a Pixmap, we can actually display this on multiple windows -- even though we only need a single Pixmap instance to do this. If -caching wasn't done then it would be necessary to create +cached. This cache is on a per-device basis for all glyphs except +widget-glyphs, and on a per-window basis for widgets-glyphs. The +caching is done by `image_instantiate' and is necessary because it is +generally possible to display an image-instance in multiple domains. +For instance if we create a Pixmap, we can actually display this on +multiple windows - even though we only need a single Pixmap instance to +do this. If caching wasn't done then it would be necessary to create image-instances for every displayable occurrence of a glyph - and every usage - and this would be extremely memory and cpu intensive. Widget-glyphs (a.k.a native widgets) are not cached in this way. This is because widget-glyph image-instances on screen are toolkit windows, and thus cannot be reused in multiple XEmacs domains. Thus -widget-glyphs are cached on a window basis. +widget-glyphs are cached on an XEmacs window basis. Any action on a glyph first consults the cache before actually instantiating a widget. +Glyph Instantiation +=================== + + Glyph instantiation is a hairy topic and requires some explanation. +The guts of glyph instantiation is contained within +`image_instantiate'. A glyph contains an image which is a specifier. +When a glyph function - for instance `Fglyph_height' - asks for a +property of the glyph that can only be determined from its instantiated +state, then the glyph image is instantiated and an image instance +created. The instantiation process is governed by the specifier code +and goes through a series of steps: + + * Validation. Instantiation of image instances happens dynamically - + often within the guts of redisplay. Thus it is often not feasible + to catch instantiator errors at instantiation time. Instead the + instantiator is validated at the time it is added to the image + specifier. This function is defined by `image_validate' and at a + simple level validates keyword value pairs. + + * Duplication. The specifier code by default takes a copy of the + instantiator. This is reasonable for most specifiers but in the + case of widget-glyphs can be problematic, since some of the + properties in the instantiator - for instance callbacks - could + cause infinite recursion in the copying process. Thus the image + code defines a function - `image_copy_instantiator' - which will + selectively copy values. This is controlled by the way that a + keyword is defined either using `IIFORMAT_VALID_KEYWORD' or + `IIFORMAT_VALID_NONCOPY_KEYWORD'. Note that the image caching and + redisplay code relies on instantiator copying to ensure that + current and new instantiators are actually different rather than + referring to the same thing. + + * Normalization. Once the instantiator has been copied it must be + converted into a form that is viable at instantiation time. This + can involve no changes at all, but typically involves things like + converting file names to the actual data. This function is defined + by `image_going_to_add' and `normalize_image_instantiator'. + + * Instantiation. When an image instance is actually required for + display it is instantiated using `image_instantiate'. This + involves calling instantiate methods that are specific to the type + of image being instantiated. + + The final instantiation phase also involves a number of steps. In +order to understand these we need to describe a number of concepts. + + An image is instantiated in a "domain", where a domain can be any +one of a device, frame, window or image-instance. The domain gives the +image-instance context and identity and properties that affect the +appearance of the image-instance may be different for the same glyph +instantiated in different domains. An example is the face used to +display the image-instance. + + Although an image is instantiated in a particular domain the +instantiation domain is not necessarily the domain in which the +image-instance is cached. For example a pixmap can be instantiated in a +window be actually be cached on a per-device basis. The domain in which +the image-instance is actually cached is called the "governing-domain". +A governing-domain is currently either a device or a window. +Widget-glyphs and text-glyphs have a window as a governing-domain, all +other image-instances have a device as the governing-domain. The +governing domain for an image-instance is determined using the +governing_domain image-instance method. + +Widget-Glyphs +============= + Widget-Glyphs in the MS-Windows Environment =========================================== @@ -730,10 +798,11 @@ Widget-Glyphs in the MS-Windows Environment Widget-Glyphs in the X Environment ================================== - Widget-glyphs under X make heavy use of lwlib for manipulating the -native toolkit objects. This is primarily so that different toolkits can -be supported for widget-glyphs, just as they are supported for features -such as menubars etc. + Widget-glyphs under X make heavy use of lwlib (*note Lucid Widget +Library::) for manipulating the native toolkit objects. This is +primarily so that different toolkits can be supported for +widget-glyphs, just as they are supported for features such as menubars +etc. Lwlib is extremely poorly documented and quite hairy so here is my understanding of what goes on. @@ -813,7 +882,7 @@ argument, which is the callback function or form given in the menu's description.  -File: internals.info, Node: Subprocesses, Next: Interface to X Windows, Prev: Menus, Up: Top +File: internals.info, Node: Subprocesses, Next: Interface to the X Window System, Prev: Menus, Up: Top Subprocesses ************ @@ -887,175 +956,155 @@ Subprocesses it is using pipes.  -File: internals.info, Node: Interface to X Windows, Next: Index, Prev: Subprocesses, Up: Top +File: internals.info, Node: Interface to the X Window System, Next: Index, Prev: Subprocesses, Up: Top -Interface to X Windows -********************** +Interface to the X Window System +******************************** - Not yet documented. + Mostly undocumented. + +* Menu: + +* Lucid Widget Library:: An interface to various widget sets.  -File: internals.info, Node: Index, Prev: Interface to X Windows, Up: Top +File: internals.info, Node: Lucid Widget Library, Up: Interface to the X Window System -Index -***** +Lucid Widget Library +==================== + + Lwlib is extremely poorly documented and quite hairy. The author(s) +blame that on X, Xt, and Motif, with some justice, but also sufficient +hypocrisy to avoid drawing the obvious conclusion about their own work. + + The Lucid Widget Library is composed of two more or less independent +pieces. The first, as the name suggests, is a set of widgets. These +widgets are intended to resemble and improve on widgets provided in the +Motif toolkit but not in the Athena widgets, including menubars and +scrollbars. Recent additions by Andy Piper integrate some "modern" +widgets by Edward Falk, including checkboxes, radio buttons, progress +gauges, and index tab controls (aka notebooks). + + The second piece of the Lucid widget library is a generic interface +to several toolkits for X (including Xt, the Athena widget set, and +Motif, as well as the Lucid widgets themselves) so that core XEmacs +code need not know which widget set has been used to build the +graphical user interface. * Menu: -* Amdahl Corporation: XEmacs. -* Andreessen, Marc: XEmacs. -* asynchronous subprocesses: Modules for Interfacing with the Operating System. -* Baur, Steve: XEmacs. -* Benson, Eric: Lucid Emacs. -* bridge, playing: XEmacs From the Outside. -* Buchholz, Martin: XEmacs. -* Bufbyte: Character-Related Data Types. -* Bufpos: Character-Related Data Types. -* Bytecount: Character-Related Data Types. -* bytecount_to_charcount: Working With Character and Byte Positions. -* Bytind: Character-Related Data Types. -* C vs. Lisp: The Lisp Language. -* caller-protects (GCPRO rule): Writing Lisp Primitives. -* case table: Modules for Other Aspects of the Lisp Interpreter and Object System. -* Charcount: Character-Related Data Types. -* charcount_to_bytecount: Working With Character and Byte Positions. -* charptr_emchar: Working With Character and Byte Positions. -* charptr_n_addr: Working With Character and Byte Positions. -* closer: Lstream Methods. -* closure: The XEmacs Object System (Abstractly Speaking). -* Coding for Mule: Coding for Mule. -* Common Lisp: The Lisp Language. -* compact_string_chars: compact_string_chars. -* conservative garbage collection: GCPROing. -* copy-on-write: General Coding Rules. -* critical redisplay sections: Critical Redisplay Sections. -* DEC_CHARPTR: Working With Character and Byte Positions. -* Devin, Matthieu: Lucid Emacs. -* display order of extents: Mathematics of Extent Ordering. -* dynamic array: Low-Level Modules. -* dynamic scoping: The Lisp Language. -* dynamic types: The Lisp Language. -* Emchar: Character-Related Data Types. -* Energize: Lucid Emacs. -* Epoch <1>: XEmacs. -* Epoch: Lucid Emacs. -* Extbyte: Character-Related Data Types. -* Extcount: Character-Related Data Types. -* extent fragment: Extent Fragments. -* extent mathematics: Mathematics of Extent Ordering. -* extent ordering: Mathematics of Extent Ordering. -* extents, display order: Mathematics of Extent Ordering. -* external widget: Modules for Interfacing with X Windows. -* flusher: Lstream Methods. -* Free Software Foundation: A History of Emacs. -* FSF: A History of Emacs. -* FSF Emacs <1>: GNU Emacs 20. -* FSF Emacs: GNU Emacs 19. -* garbage collection: Garbage Collection. -* garbage collection protection: Writing Lisp Primitives. -* garbage collection step by step: Garbage Collection - Step by Step. -* garbage collection, conservative: GCPROing. -* garbage collection, invocation: Invocation. -* garbage_collect_1: garbage_collect_1. -* gc_sweep: gc_sweep. -* GNU Emacs 19: GNU Emacs 19. -* GNU Emacs 20: GNU Emacs 20. -* Gosling, James <1>: The Lisp Language. -* Gosling, James: Through Version 18. -* Great Usenet Renaming: Through Version 18. -* Hackers (Steven Levy): A History of Emacs. -* hierarchy of windows: Window Hierarchy. -* history of Emacs: A History of Emacs. -* Illinois, University of: XEmacs. -* INC_CHARPTR: Working With Character and Byte Positions. -* interactive: Modules for Standard Editing Operations. -* interning: The XEmacs Object System (Abstractly Speaking). -* ITS (Incompatible Timesharing System): A History of Emacs. -* Java: The Lisp Language. -* Java vs. Lisp: The Lisp Language. -* Jones, Kyle: XEmacs. -* Kaplan, Simon: XEmacs. -* Levy, Steven: A History of Emacs. -* line start cache: Line Start Cache. -* Lisp vs. C: The Lisp Language. -* Lisp vs. Java: The Lisp Language. -* lstream: Modules for Interfacing with the File System. -* Lstream_close: Lstream Functions. -* Lstream_fgetc: Lstream Functions. -* Lstream_flush: Lstream Functions. -* Lstream_fputc: Lstream Functions. -* Lstream_fungetc: Lstream Functions. -* Lstream_getc: Lstream Functions. -* Lstream_new: Lstream Functions. -* Lstream_putc: Lstream Functions. -* Lstream_read: Lstream Functions. -* Lstream_reopen: Lstream Functions. -* Lstream_rewind: Lstream Functions. -* Lstream_set_buffering: Lstream Functions. -* Lstream_ungetc: Lstream Functions. -* Lstream_unread: Lstream Functions. -* Lstream_write: Lstream Functions. -* Lucid Emacs: Lucid Emacs. -* Lucid Inc.: Lucid Emacs. -* mark and sweep: Garbage Collection. -* mark method <1>: lrecords. -* mark method: Modules for Other Aspects of the Lisp Interpreter and Object System. -* mark_object: mark_object. -* marker: Lstream Methods. -* mathematics of extents: Mathematics of Extent Ordering. -* MAX_EMCHAR_LEN: Working With Character and Byte Positions. -* merging attempts: XEmacs. -* MIT: A History of Emacs. -* Mlynarik, Richard: GNU Emacs 19. -* MULE merged XEmacs appears: XEmacs. -* NAS: Modules for Interfacing with the Operating System. -* native sound: Modules for Interfacing with the Operating System. -* network connections: Modules for Interfacing with the Operating System. -* network sound: Modules for Interfacing with the Operating System. -* Niksic, Hrvoje: XEmacs. -* pane: Modules for the Basic Displayable Lisp Objects. -* permanent objects: The XEmacs Object System (Abstractly Speaking). -* pi, calculating: XEmacs From the Outside. -* pseudo_closer: Lstream Methods. -* read syntax: The XEmacs Object System (Abstractly Speaking). -* read-eval-print: XEmacs From the Outside. -* reader: Lstream Methods. -* Redisplay Piece by Piece: Redisplay Piece by Piece. -* relocating allocator: Low-Level Modules. -* rename to XEmacs: XEmacs. -* rewinder: Lstream Methods. -* RMS: A History of Emacs. -* scanner: Modules for Other Aspects of the Lisp Interpreter and Object System. -* scoping, dynamic: The Lisp Language. -* seekable_p: Lstream Methods. -* selections: Modules for Interfacing with X Windows. -* set_charptr_emchar: Working With Character and Byte Positions. -* Sexton, Harlan: Lucid Emacs. -* sound, native: Modules for Interfacing with the Operating System. -* sound, network: Modules for Interfacing with the Operating System. -* SPARCWorks: XEmacs. -* Stallman, Richard: A History of Emacs. -* subprocesses, asynchronous: Modules for Interfacing with the Operating System. -* subprocesses, synchronous: Modules for Interfacing with the Operating System. -* Sun Microsystems: XEmacs. -* sweep_bit_vectors_1: sweep_bit_vectors_1. -* sweep_lcrecords_1: sweep_lcrecords_1. -* sweep_strings: sweep_strings. -* synchronous subprocesses: Modules for Interfacing with the Operating System. -* taxes, doing: XEmacs From the Outside. -* TECO: A History of Emacs. -* temporary objects: The XEmacs Object System (Abstractly Speaking). -* Thompson, Chuck: XEmacs. -* types, dynamic: The Lisp Language. -* University of Illinois: XEmacs. -* Win-Emacs: XEmacs. -* window (in Emacs): Modules for the Basic Displayable Lisp Objects. -* window hierarchy: Window Hierarchy. -* window point internals: The Window Object. -* Wing, Ben: XEmacs. -* writer: Lstream Methods. -* XEmacs: XEmacs. -* XEmacs goes it alone: XEmacs. -* Zawinski, Jamie: Lucid Emacs. +* Generic Widget Interface:: The lwlib generic widget interface. +* Scrollbars:: +* Menubars:: +* Checkboxes and Radio Buttons:: +* Progress Bars:: +* Tab Controls:: + + +File: internals.info, Node: Generic Widget Interface, Next: Scrollbars, Up: Lucid Widget Library + +Generic Widget Interface +------------------------ + + In general in any toolkit a widget may be a composite object. In Xt, +all widgets have an X window that they manage, but typically a complex +widget will have widget children, each of which manages a subwindow of +the parent widget's X window. These children may themselves be +composite widgets. Thus a widget is actually a tree or hierarchy of +widgets. + + For each toolkit widget, lwlib maintains a tree of `widget_values' +which mirror the hierarchical state of Xt widgets (including Motif, +Athena, 3D Athena, and Falk's widget sets). Each `widget_value' has +`contents' member, which points to the head of a linked list of its +children. The linked list of siblings is chained through the `next' +member of `widget_value'. + + +-----------+ + | composite | + +-----------+ + | + | contents + V + +-------+ next +-------+ next +-------+ + | child |----->| child |----->| child | + +-------+ +-------+ +-------+ + | + | contents + V + +-------------+ next +-------------+ + | grand child |----->| grand child | + +-------------+ +-------------+ + + The `widget_value' hierarchy of a composite widget with two simple + children and one composite child. + + The `widget_instance' structure maintains the inverse view of the +tree. As for the `widget_value', siblings are chained through the +`next' member. However, rather than naming children, the +`widget_instance' tree links to parents. + + +-----------+ + | composite | + +-----------+ + A + | parent + | + +-------+ next +-------+ next +-------+ + | child |----->| child |----->| child | + +-------+ +-------+ +-------+ + A + | parent + | + +-------------+ next +-------------+ + | grand child |----->| grand child | + +-------------+ +-------------+ + + The `widget_value' hierarchy of a composite widget with two simple + children and one composite child. + + This permits widgets derived from different toolkits to be updated +and manipulated generically by the lwlib library. For instance +`update_one_widget_instance' can cope with multiple types of widget and +multiple types of toolkit. Each element in the widget hierarchy is +updated from its corresponding `widget_value' by walking the +`widget_value' tree. This has desirable properties. For example, +`lw_modify_all_widgets' is called from `glyphs-x.c' and updates all the +properties of a widget without having to know what the widget is or +what toolkit it is from. Unfortunately this also has its hairy +properties; the lwlib code quite complex. And of course lwlib has to +know at some level what the widget is and how to set its properties. + + The `widget_instance' structure also contains a pointer to the root +of its tree. Widget instances are further confi + + +File: internals.info, Node: Scrollbars, Next: Menubars, Prev: Generic Widget Interface, Up: Lucid Widget Library + +Scrollbars +---------- + + +File: internals.info, Node: Menubars, Next: Checkboxes and Radio Buttons, Prev: Scrollbars, Up: Lucid Widget Library + +Menubars +-------- + + +File: internals.info, Node: Checkboxes and Radio Buttons, Next: Progress Bars, Prev: Menubars, Up: Lucid Widget Library + +Checkboxes and Radio Buttons +---------------------------- + + +File: internals.info, Node: Progress Bars, Next: Tab Controls, Prev: Checkboxes and Radio Buttons, Up: Lucid Widget Library + +Progress Bars +------------- + + +File: internals.info, Node: Tab Controls, Prev: Progress Bars, Up: Lucid Widget Library +Tab Controls +------------