Mercurial > hg > xemacs-beta

comparison man/internals/internals.texi @ 4917:fce43cb76a1c

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
xlike cleanup, documentation -------------------- ChangeLog entries follow: -------------------- man/ChangeLog addition: 2010-02-03 Ben Wing <ben@xemacs.org> * internals/internals.texi (Top): * internals/internals.texi (Evaluation; Stack Frames; Bindings): * internals/internals.texi (Ben's README): * internals/internals.texi (Consoles; Devices; Frames; Windows): * internals/internals.texi (Window Hierarchy): * internals/internals.texi (The Window Object): * internals/internals.texi (Modules for the Basic Displayable Lisp Objects): * internals/internals.texi (Window-System Support): * internals/internals.texi (Creating a Window-System Type): * internals/internals.texi (Discussion -- Garbage Collection): Update the part at the top about how to maintain the file with more tips. Add a chapter on "window-system support" describing in a general way how the support for different window systems/device types works, including the separation between device-independent and device-dependent parts, device methods, the specific device types and the "xlike" pseudo-type. src/ChangeLog addition: 2010-02-03 Ben Wing <ben@xemacs.org> * Makefile.in.in: * Makefile.in.in (x_objs): * Makefile.in.in (gtk_gui_objs): * console-xlike-inc.h: * depend: * device-x.c: * emacs.c: * gccache-gtk.h: * gccache-gtk.h (gc_cache_lookup): * gccache-x.c: * gccache-x.c (GCCACHE_HASH): * gccache-x.h: * toolbar-gtk.c: * toolbar-gtk.c (gtk_initialize_frame_toolbars): * toolbar-x.c: * toolbar-x.c (x_initialize_frame_toolbars): * toolbar-xlike.c: * toolbar-xlike.c (xlike_draw_blank_toolbar_button): * toolbar-xlike.c (xlike_output_toolbar_button): * toolbar-xlike.c (xlike_get_button_size): * toolbar-xlike.c (XLIKE_OUTPUT_BUTTONS_LOOP): * toolbar-xlike.c (xlike_output_toolbar): * toolbar-xlike.c (xlike_clear_toolbar): * toolbar-xlike.c (xlike_output_frame_toolbars): * toolbar-xlike.c (xlike_clear_frame_toolbars): * toolbar-xlike.c (xlike_redraw_exposed_toolbar): * toolbar-xlike.c (xlike_redraw_exposed_toolbars): * toolbar-xlike.c (xlike_redraw_frame_toolbars): * toolbar-xlike.h: * toolbar-xlike.h (xlike_clear_frame_toolbars): Rename some files to make them consistent with general naming rules: xgccache.c -> gccache-x.c xgccache.h -> gccache-x.h toolbar-common.c -> toolbar-xlike.c toolbar-common.h -> toolbar-xlike.h Fix include-file references. Also change the names of functions in now-named toolbar-xlike.c to be xlike_foo() instead of common_foo(). Add a longish comment in console-xlike-inc.h describing the "xlike" system, how it works and what the various files are used for.
author Ben Wing <ben@xemacs.org>
date Wed, 03 Feb 2010 02:46:50 -0600
parents 755ae5b97edb
children cbe181529c34
comparison
equal deleted inserted replaced
4916:a6c778975d7d 4917:fce43cb76a1c
127 @ifinfo 127 @ifinfo
128 This Info file contains v21.5 of the XEmacs Internals Manual, October 2004. 128 This Info file contains v21.5 of the XEmacs Internals Manual, October 2004.
129 @end ifinfo 129 @end ifinfo
130 130
131 @ignore 131 @ignore
132 Don't update this by hand!!!!!! 132 Tips for maintaining this file:
133 Use C-u C-c C-u m (aka C-u M-x texinfo-master-list). 133
134 NOTE: This command does not include the Index:: menu entry. 134 1. Updating the forward, back and up pointers in a @@node line:
135 ---------------------------------------------------------------
136
137 Don't do it by hand!
138
139 Use C-c C-u C-e (aka M-x texinfo-every-node-update).
140
141 2. Updating the menus:
142 ----------------------
143
144 This section describes how to update the menus at the end of chapters,
145 sections with subsections, etc., and the master menu near the top of
146 the file:
147
148 Don't do it by hand!
149
150 Use C-u C-c C-u m (aka C-u M-x texinfo-master-menu).
151 N
152 OTE: This command does not include the Index:: menu entry.
135 You must add it by hand. 153 You must add it by hand.
136 154
137 Here are some useful Lisp routines for quickly Texinfo-izing text that 155 3. Converting plain text into Texinfo:
138 has been formatted into ASCII lists and tables. 156 --------------------------------------
157
158 3a. Here are some useful Lisp routines for quickly Texinfo-izing text
159 that has been formatted into ASCII lists and tables.
160
161 Note: to define these routines, put point after the end of the definition
162 and type C-x C-e.
139 163
140 (defun list-to-texinfo (b e) 164 (defun list-to-texinfo (b e)
141 "Convert the selected region from an ASCII list to a Texinfo list." 165 "Convert the selected region from an ASCII list to a Texinfo list."
142 (interactive "r") 166 (interactive "r")
143 (save-restriction 167 (save-restriction
247 (delete-char) 271 (delete-char)
248 (insert "\n")))) 272 (insert "\n"))))
249 (beginning-of-line) 273 (beginning-of-line)
250 (insert "@end table\n"))) 274 (insert "@end table\n")))
251 275
252 A useful Lisp routine for adding markup based on conventions used in plain 276 3b. A useful Lisp routine for adding markup based on conventions used
253 text files; see doc string below. 277 in plain text files; see doc string below.
254 278
255 (defun convert-text-to-texinfo (&optional no-narrow) 279 (defun convert-text-to-texinfo (&optional no-narrow)
256 "Convert text to Texinfo. 280 "Convert text to Texinfo.
257 If the region is active, do the region; otherwise, go from point to the end 281 If the region is active, do the region; otherwise, go from point to the end
258 of the buffer. This query-replaces for various kinds of conventions used 282 of the buffer. This query-replaces for various kinds of conventions used
259 in text: @code{} surrounded by ` and ' or followed by a (); @strong{} 283 in text: @code{} surrounded by ` and ' or followed by a (); @strong{}
260 surrounded by *'s; @file{} something that looks like a file name." 284 surrounded by *'s; @file{} something that looks like a file name."
261 (interactive) 285 (interactive)
262 (if (region-active-p) 286 (if (and (not no-narrow) (region-active-p))
263 (save-restriction 287 (save-restriction
264 (narrow-to-region (region-beginning) (region-end)) 288 (narrow-to-region (region-beginning) (region-end))
265 (convert-comments-to-texinfo t)) 289 (convert-text-to-texinfo t))
266 (let ((p (point)) 290 (let ((p (point))
267 (case-replace nil)) 291 (case-replace nil))
268 (query-replace-regexp "`\\([^']+\\)'\\([^']\\)" "@code{\\1}\\2" nil) 292 (query-replace-regexp "`\\([^']+\\)'\\([^']\\)" "@code{\\1}\\2" nil)
269 (goto-char p) 293 (goto-char p)
270 (query-replace-regexp "\\(\\Sw\\)\\*\\(\\(?:\\s_\\|\\sw\\)+\\)\\*\\([^A-Za-z.}]\\)" "\\1@strong{\\2}\\3" nil) 294 (query-replace-regexp "\\(\\Sw\\)\\*\\(\\(?:\\s_\\|\\sw\\)+\\)\\*\\([^A-Za-z.}]\\)" "\\1@strong{\\2}\\3" nil)
272 (query-replace-regexp "\\(\\(\\s_\\|\\sw\\)+()\\)\\([^}]\\)" "@code{\\1}\\3" nil) 296 (query-replace-regexp "\\(\\(\\s_\\|\\sw\\)+()\\)\\([^}]\\)" "@code{\\1}\\3" nil)
273 (goto-char p) 297 (goto-char p)
274 (query-replace-regexp "\\(\\(\\s_\\|\\sw\\)+\\.[A-Za-z]+\\)\\([^A-Za-z.}]\\)" "@file{\\1}\\3" nil) 298 (query-replace-regexp "\\(\\(\\s_\\|\\sw\\)+\\.[A-Za-z]+\\)\\([^A-Za-z.}]\\)" "@file{\\1}\\3" nil)
275 ))) 299 )))
276 300
277 Macro the generate the "Future Work" section from a title; put 301 4. Adding new sections:
278 point at beginning. 302 -----------------------
303
304 NOTE: These are in the form of macros. #### FIXME Convert them to
305 proper functions. To edit these macros, define them and then use
306 M-x edit-kbd-macro.
307
308 Macro to generate the "Future Work" section from a title; put
309 point at the beginning of the title.
279 310
280 (defalias 'make-future (read-kbd-macro 311 (defalias 'make-future (read-kbd-macro
281 "<S-end> <f3> <home> @node SPC <end> RET @section SPC <f4> <home> <up> <C-right> <right> Future SPC Work SPC - - SPC <home> <down> <C-right> <right> Future SPC Work SPC - - SPC <end> RET @cindex SPC future SPC work, SPC <f4> C-r , RET C-x C-x M-l RET @cindex SPC <f4> <home> <C-right> <S-end> M-l , SPC future SPC work RET")) 312 "<S-end> M-w <home> @node SPC <end> RET @section SPC C-y <home> <up> <C-right> <right> Future SPC Work SPC - - SPC <home> <down> <C-right> <right> Future SPC Work SPC - - SPC <end> RET @cindex SPC future SPC work, SPC C-y C-r , RET C-x C-x M-l RET @cindex SPC C-y <home> <C-right> <S-end> M-l , SPC future SPC work RET"))
282 313
283 Similar but generates a "Discussion" section. 314 Similar but generates a "Discussion" section.
284 315
285 (defalias 'make-discussion (read-kbd-macro 316 (defalias 'make-discussion (read-kbd-macro
286 "<S-end> <f3> <home> @node SPC <end> RET @section SPC <f4> <home> <up> <C-right> <right> Discussion SPC - - SPC <home> <down> <C-right> <right> Discussion SPC - - SPC <end> RET @cindex SPC discussion, SPC <f4> C-r , RET C-x C-x M-l RET @cindex SPC <f4> <home> <C-right> <S-end> M-l , SPC discussion RET")) 317 "<S-end> M-w <home> @node SPC <end> RET @section SPC C-y <home> <up> <C-right> <right> Discussion SPC - - SPC <home> <down> <C-right> <right> Discussion SPC - - SPC <end> RET @cindex SPC discussion, SPC C-y C-r , RET C-x C-x M-l RET @cindex SPC C-y <home> <C-right> <S-end> M-l , SPC discussion RET"))
287 318
288 Similar but generates an "Old Future Work" section. 319 Similar but generates an "Old Future Work" section.
289 320
290 (defalias 'make-old-future (read-kbd-macro 321 (defalias 'make-old-future (read-kbd-macro
291 "<S-end> <f3> <home> @node SPC <end> RET @section SPC <f4> <home> <up> <C-right> <right> Old SPC Future SPC Work SPC - - SPC <home> <down> <C-right> <right> Old SPC Future SPC Work SPC - - SPC <end> RET @cindex SPC old SPC future SPC work, SPC <f4> C-r , RET C-x C-x M-l RET @cindex SPC <f4> <home> <C-right> <S-end> M-l , SPC old SPC future SPC work RET")) 322 "<S-end> M-w <home> @node SPC <end> RET @section SPC C-y <home> <up> <C-right> <right> Old SPC Future SPC Work SPC - - SPC <home> <down> <C-right> <right> Old SPC Future SPC Work SPC - - SPC <end> RET @cindex SPC old SPC future SPC work, SPC C-y C-r , RET C-x C-x M-l RET @cindex SPC C-y <home> <C-right> <S-end> M-l , SPC old SPC future SPC work RET"))
292 323
293 Similar but generates a general section. 324 Similar but generates a general section.
294 325
295 (defalias 'make-section (read-kbd-macro 326 (defalias 'make-section (read-kbd-macro
296 "<S-end> <f3> <home> @node SPC <end> RET @section SPC <f4> RET @cindex SPC C-SPC C-g <f4> C-x C-x M-l <home> <down>")) 327 "<S-end> M-w <home> @node SPC <end> RET @section SPC C-y RET @cindex SPC C-SPC C-g C-y C-x C-x M-l <home> <down>"))
297 328
298 Similar but generates a general subsection. 329 Similar but generates a general subsection.
299 330
300 (defalias 'make-subsection (read-kbd-macro 331 (defalias 'make-subsection (read-kbd-macro
301 "<S-end> <f3> <home> @node SPC <end> RET @subsection SPC <f4> RET @cindex SPC C-SPC C-g <f4> C-x C-x M-l <home> <down>")) 332 "<S-end> M-w <home> @node SPC <end> RET @subsection SPC C-y RET @cindex SPC C-SPC C-g C-y C-x C-x M-l <home> <down>"))
302 @end ignore 333 @end ignore
303 334
304 @menu 335 @menu
305 * Introduction:: Overview of this manual. 336 * Introduction:: Overview of this manual.
306 * Authorship of XEmacs:: 337 * Authorship of XEmacs::
326 * Symbols and Variables:: 357 * Symbols and Variables::
327 * Buffers:: 358 * Buffers::
328 * Text:: 359 * Text::
329 * Multilingual Support:: 360 * Multilingual Support::
330 * Consoles; Devices; Frames; Windows:: 361 * Consoles; Devices; Frames; Windows::
362 * Window-System Support::
331 * The Redisplay Mechanism:: 363 * The Redisplay Mechanism::
332 * Extents:: 364 * Extents::
333 * Faces:: 365 * Faces::
334 * Glyphs:: 366 * Glyphs::
335 * Specifiers:: 367 * Specifiers::
449 481
450 Evaluation; Stack Frames; Bindings 482 Evaluation; Stack Frames; Bindings
451 483
452 * Evaluation:: 484 * Evaluation::
453 * Dynamic Binding; The specbinding Stack; Unwind-Protects:: 485 * Dynamic Binding; The specbinding Stack; Unwind-Protects::
454 * Simple Special Operators:: 486 * Simple Special Operators::
455 * Catch and Throw:: 487 * Catch and Throw::
456 * Error Trapping:: 488 * Error Trapping::
457 489
458 Symbols and Variables 490 Symbols and Variables
459 491
556 588
557 * Introduction to Consoles; Devices; Frames; Windows:: 589 * Introduction to Consoles; Devices; Frames; Windows::
558 * Point:: 590 * Point::
559 * Window Hierarchy:: 591 * Window Hierarchy::
560 * The Window Object:: 592 * The Window Object::
561 * Creating a New Console/Device/Frame Type::
562 * Modules for the Basic Displayable Lisp Objects:: 593 * Modules for the Basic Displayable Lisp Objects::
594
595 Window-System Support
596
597 * Creating a Window-System Type::
563 598
564 The Redisplay Mechanism 599 The Redisplay Mechanism
565 600
566 * Critical Redisplay Sections:: 601 * Critical Redisplay Sections::
567 * Line Start Cache:: 602 * Line Start Cache::
738 * Discussion -- Packages:: 773 * Discussion -- Packages::
739 * Discussion -- Distribution Layout:: 774 * Discussion -- Distribution Layout::
740 775
741 Discussion -- Garbage Collection 776 Discussion -- Garbage Collection
742 777
743 * Discussion -- KKCC:: 778 * Discussion -- KKCC::
744 * Discussion -- Incremental Collector:: 779 * Discussion -- Incremental Collector::
745 * Discussion -- Pure Space:: 780 * Discussion -- Pure Space::
746 * Discussion -- Hashtable-Based Marking and Cleanup:: 781 * Discussion -- Hashtable-Based Marking and Cleanup::
747 * Discussion -- The Anti-Cons:: 782 * Discussion -- The Anti-Cons::
748 783
749 Old Future Work 784 Old Future Work
8952 @cindex bindings, evaluation; stack frames; 8987 @cindex bindings, evaluation; stack frames;
8953 8988
8954 @menu 8989 @menu
8955 * Evaluation:: 8990 * Evaluation::
8956 * Dynamic Binding; The specbinding Stack; Unwind-Protects:: 8991 * Dynamic Binding; The specbinding Stack; Unwind-Protects::
8957 * Simple Special Operators:: 8992 * Simple Special Operators::
8958 * Catch and Throw:: 8993 * Catch and Throw::
8959 * Error Trapping:: 8994 * Error Trapping::
8960 @end menu 8995 @end menu
8961 8996
8962 @node Evaluation, Dynamic Binding; The specbinding Stack; Unwind-Protects, Evaluation; Stack Frames; Bindings, Evaluation; Stack Frames; Bindings 8997 @node Evaluation, Dynamic Binding; The specbinding Stack; Unwind-Protects, Evaluation; Stack Frames; Bindings, Evaluation; Stack Frames; Bindings
17139 present in the fsf version, for compatibility. 17174 present in the fsf version, for compatibility.
17140 @end itemize 17175 @end itemize
17141 17176
17142 17177
17143 17178
17144 @node Consoles; Devices; Frames; Windows, The Redisplay Mechanism, Multilingual Support, Top 17179 @node Consoles; Devices; Frames; Windows, Window-System Support, Multilingual Support, Top
17145 @chapter Consoles; Devices; Frames; Windows 17180 @chapter Consoles; Devices; Frames; Windows
17146 @cindex consoles; devices; frames; windows 17181 @cindex consoles; devices; frames; windows
17147 @cindex devices; frames; windows, consoles; 17182 @cindex devices; frames; windows, consoles;
17148 @cindex frames; windows, consoles; devices; 17183 @cindex frames; windows, consoles; devices;
17149 @cindex windows, consoles; devices; frames; 17184 @cindex windows, consoles; devices; frames;
17151 @menu 17186 @menu
17152 * Introduction to Consoles; Devices; Frames; Windows:: 17187 * Introduction to Consoles; Devices; Frames; Windows::
17153 * Point:: 17188 * Point::
17154 * Window Hierarchy:: 17189 * Window Hierarchy::
17155 * The Window Object:: 17190 * The Window Object::
17156 * Creating a New Console/Device/Frame Type::
17157 * Modules for the Basic Displayable Lisp Objects:: 17191 * Modules for the Basic Displayable Lisp Objects::
17158 @end menu 17192 @end menu
17159 17193
17160 @node Introduction to Consoles; Devices; Frames; Windows, Point, Consoles; Devices; Frames; Windows, Consoles; Devices; Frames; Windows 17194 @node Introduction to Consoles; Devices; Frames; Windows, Point, Consoles; Devices; Frames; Windows, Consoles; Devices; Frames; Windows
17161 @section Introduction to Consoles; Devices; Frames; Windows 17195 @section Introduction to Consoles; Devices; Frames; Windows
17321 frames have no root window, and the @code{next} of the minibuffer window 17355 frames have no root window, and the @code{next} of the minibuffer window
17322 is @code{nil} but the @code{prev} points to itself. (#### This is an 17356 is @code{nil} but the @code{prev} points to itself. (#### This is an
17323 artifact that should be fixed.) 17357 artifact that should be fixed.)
17324 @end enumerate 17358 @end enumerate
17325 17359
17326 @node The Window Object, Creating a New Console/Device/Frame Type, Window Hierarchy, Consoles; Devices; Frames; Windows 17360 @node The Window Object, Modules for the Basic Displayable Lisp Objects, Window Hierarchy, Consoles; Devices; Frames; Windows
17327 @section The Window Object 17361 @section The Window Object
17328 @cindex window object, the 17362 @cindex window object, the
17329 @cindex object, the window 17363 @cindex object, the window
17330 17364
17331 Windows have the following accessible fields: 17365 Windows have the following accessible fields:
17429 holds the mark position that made one end of that region. Otherwise, 17463 holds the mark position that made one end of that region. Otherwise,
17430 this field is @code{nil}. 17464 this field is @code{nil}.
17431 @end table 17465 @end table
17432 17466
17433 17467
17434 @node Creating a New Console/Device/Frame Type, Modules for the Basic Displayable Lisp Objects, The Window Object, Consoles; Devices; Frames; Windows 17468 @node Modules for the Basic Displayable Lisp Objects, , The Window Object, Consoles; Devices; Frames; Windows
17435 @section Creating a New Console, Device, or Frame Type 17469 @section Modules for the Basic Displayable Lisp Objects
17470 @cindex modules for the basic displayable Lisp objects
17471 @cindex displayable Lisp objects, modules for the basic
17472 @cindex Lisp objects, modules for the basic displayable
17473 @cindex objects, modules for the basic displayable Lisp
17474
17475 @example
17476 @file{console-msw.c}
17477 @file{console-msw.h}
17478 @file{console-stream.c}
17479 @file{console-stream.h}
17480 @file{console-tty.c}
17481 @file{console-tty.h}
17482 @file{console-x.c}
17483 @file{console-x.h}
17484 @file{console.c}
17485 @file{console.h}
17486 @end example
17487
17488 These modules implement the @dfn{console} Lisp object type. A console
17489 contains multiple display devices, but only one keyboard and mouse.
17490 Most of the time, a console will contain exactly one device.
17491
17492 @strong{This model may no longer suffice.} The X Window System (at
17493 least) now supports a variety of input devices, including touchscreens
17494 and tablets, as well as the traditional keyboard and mouse, and may even
17495 be able to support multiple instances of a single type of input device
17496 (especially pointing devices) on a single console.
17497
17498 Consoles are the top of a lisp object inclusion hierarchy. Consoles
17499 contain devices, which contain frames, which contain windows.
17500
17501
17502
17503 @example
17504 @file{device-msw.c}
17505 @file{device-tty.c}
17506 @file{device-x.c}
17507 @file{device.c}
17508 @file{device.h}
17509 @end example
17510
17511 These modules implement the @dfn{device} Lisp object type. This
17512 abstracts a particular screen or connection on which frames are
17513 displayed. As with Lisp objects, event interfaces, and other
17514 subsystems, the device code is separated into a generic component that
17515 contains a standardized interface (in the form of a set of methods) onto
17516 particular device types.
17517
17518 The device subsystem defines all the methods and provides method
17519 services for not only device operations but also for the frame, window,
17520 menubar, scrollbar, toolbar, and other displayable-object subsystems.
17521 The reason for this is that all of these subsystems have the same
17522 subtypes (X, TTY, Microsoft Windows, etc.) as devices do.
17523
17524 @strong{This abstraction is probably broken} (as of late 2004), at least
17525 for X consoles, with the advent of the @strong{Xft} library. Xft is a
17526 complete break from the traditional approach to text rendering in the
17527 X11 environment, since fonts are composed of glyphs rendered by
17528 @emph{client-side} code. These glyphs are then transmitted to the
17529 server as sets of trapezoids, and displayed by the @strong{XRender}
17530 extension (where available; the X11 core protocol can also be used, but
17531 this is slow). The XRender extension is especially attractive because
17532 it allows modern image composition techniques to be used to render
17533 antialiased fonts.
17534
17535 By contrast, the traditional approach renders fonts on the server side
17536 as a collection of bitmaps. It is also possible use a @emph{font
17537 server} that knows how to render antialiased fonts, but for some reason
17538 this approach has never caught on.
17539
17540 The problem that this creates for XEmacs is that the traditional (and
17541 still popular) widget sets, the various Athena variants and the Motif
17542 widget set, are based on the server-side rendering model. Thus, even if
17543 XEmacs-specific widgets (such as the basic text window, the Lucid
17544 menubar, and the recently added tab control) can be adapted to render
17545 text via Xft, older widgets (such as buttons and labels) and ``modern''
17546 widgets derived from traditional widgets (the progress gauge) still
17547 expect their font resources to be converted to server-side fonts. Then
17548 text is rendered by calls to the core protocol via Xlib, rather than by
17549 calls to the XRender protocol via Xft.
17550
17551 It's even possible to imagine a situation where a widget is composed of
17552 components which draw their own text (@emph{predefined widgets}) as well
17553 as new components which can draw using more modern methods. Handling
17554 this will either require reworking the Emacs face mechanism to provide a
17555 way to determine whether this widget can use that font, or ways to give
17556 each of several different widgets, even different components of a given
17557 widget, a different face property. This is already an issue, as widgets
17558 generally derive their font from the gui-element face, but this might
17559 not be appropriate for widgets embedded in a buffer.
17560
17561 There seem to be two overall ways to go.
17562
17563 @enumerate
17564 @item
17565 Add face information to the Lucid widget library, and extend the
17566 coverage of that library to device types that aren't supported by it yet
17567 (MS Windows, and maybe TTY).
17568
17569 @item
17570 Create a lighter-weight interface, perhaps an extension of the device
17571 interface, that allows widgets to access face information from the
17572 device it is implemented on.
17573 @end enumerate
17574
17575
17576
17577 @example
17578 @file{frame-msw.c}
17579 @file{frame-tty.c}
17580 @file{frame-x.c}
17581 @file{frame.c}
17582 @file{frame.h}
17583 @end example
17584
17585 Each device contains one or more frames in which objects (e.g. text) are
17586 displayed. A frame corresponds to a window in the window system;
17587 usually this is a top-level window but it could potentially be one of a
17588 number of overlapping child windows within a top-level window, using the
17589 MDI (Multiple Document Interface) protocol in Microsoft Windows or a
17590 similar scheme.
17591
17592 The @file{frame-*} files implement the @dfn{frame} Lisp object type and
17593 provide the generic and device-type-specific operations on frames
17594 (e.g. raising, lowering, resizing, moving, etc.).
17595
17596
17597
17598 @example
17599 @file{window.c}
17600 @file{window.h}
17601 @end example
17602
17603 @cindex window (in Emacs)
17604 @cindex pane
17605 Each frame consists of one or more non-overlapping @dfn{windows} (better
17606 known as @dfn{panes} in standard window-system terminology) in which a
17607 buffer's text can be displayed. Windows can also have scrollbars
17608 displayed around their edges.
17609
17610 @file{window.c} and @file{window.h} implement the @dfn{window} Lisp
17611 object type and provide code to manage windows. Since windows have no
17612 associated resources in the window system (the window system knows only
17613 about the frame; no child windows or anything are used for XEmacs
17614 windows), there is no device-type-specific code here; all of that code
17615 is part of the redisplay mechanism or the code for particular object
17616 types such as scrollbars.
17617
17618
17619 @node Window-System Support, The Redisplay Mechanism, Consoles; Devices; Frames; Windows, Top
17620 @chapter Window-System Support
17621 @cindex window-system support
17622 @cindex window systems
17623 @cindex X
17624 @cindex X Windows
17625 @cindex Windows
17626 @cindex Microsoft Windows
17627 @cindex MS-Windows
17628 @cindex GTK
17629 @cindex Gnome
17630
17631 XEmacs defines the concept of a ``device type'', which approximately
17632 corresponds to a window-system type, and separates out display-related
17633 code into device-independent and device-dependent sections.
17634 Generally, the device-independent code will go into a generally-named
17635 file such as @file{redisplay.c}, while the device-dependent code goes
17636 into @file{redisplay-x.c}, @file{redisplay-gtk.c},
17637 @file{redisplay-msw.c}, etc. Device-dependent methods are called
17638 using the @code{DEVMETH} macro.
17639
17640 The following device types are defined:
17641
17642 @table @asis
17643 @item X-Windows (@code{x})
17644 This supports rendering through @code{Xlib}, widget support through
17645 @code{Xt}, and event-handling through @code{Xt}.
17646 @item Microsoft Windows (@code{msw})
17647 @item GTK/Gnome (@code{gtk})
17648 @item TTY's (@code{tty})
17649 This is used for TTY connections (e.g. running inside of an @code{xterm} or
17650 Windows console window).
17651 @item Stream devices (@code{stream})
17652 This is used for ``stream'' devices, of which there is only one -- the
17653 initial stdio device used when XEmacs is running noninteractively.
17654 @end table
17655
17656 In addition, there is a pseudo-device-type `xlike', which is used for
17657 abstracting X and GTK code that is very similar.
17658
17659 @menu
17660 * Creating a Window-System Type::
17661 @end menu
17662
17663 @node Creating a Window-System Type, , Window-System Support, Window-System Support
17664 @section Creating a Window-System Type
17665 @cindex creating a new window-system type
17666 @cindex window-system types, creating
17436 @cindex creating a new console type 17667 @cindex creating a new console type
17437 @cindex console type, creating a new 17668 @cindex console types, creating
17438 @cindex creating a new device type 17669 @cindex creating a new device type
17439 @cindex device type, creating a new 17670 @cindex device types, creating
17440 @cindex creating a new frame type 17671 @cindex creating a new frame type
17441 @cindex frame type, creating a new 17672 @cindex frame types, creating
17442 17673
17443 Unfortunately, at the present time, only the console abstraction is at 17674 Unfortunately, at the present time, only the console abstraction is
17444 all well-maintained. Device and frame internals are referred to from 17675 really well-maintained. Device and frame internals are referred to
17445 many places in the redisplay and console code. The best that can be 17676 from many places in the redisplay and console code. The best that can
17446 done therefore is to create a whole new console type, even though much 17677 be done therefore is to create a whole new console type, even though
17447 code will be shared. (Ben Wing has complained about the code 17678 much code will be shared. (Ben Wing has complained about the code
17448 duplication in the GTK+ v1 console, and probably would not be happy with 17679 duplication in the GTK+ v1 console, and probably would not be happy
17449 the unpublished Qt console or Andrew Choi's Carbon console, but it's 17680 with the unpublished Qt console or Andrew Choi's Carbon console, but
17450 hard to see how those consoles could have been done better without 17681 it's hard to see how those consoles could have been done better
17451 fixing the abstractions in the X (actually Xt), MS Windows, and tty 17682 without fixing the abstractions in the X (actually Xt), MS Windows,
17452 consoles as well as doing a complete refactoring of the console, device, 17683 and tty consoles as well as doing a complete refactoring of the
17453 and frame code.) 17684 console, device, and frame code.)
17454 17685
17455 What is desireable is sharing console, device, and frame methods across 17686 What is desireable is sharing console, device, and frame methods across
17456 platforms in a more general way, reducing the amount of duplicated code 17687 platforms in a more general way, reducing the amount of duplicated code
17457 by pulling it back into the redisplay engine proper or the Lisp modules 17688 by pulling it back into the redisplay engine proper or the Lisp modules
17458 as appropriate. For example, we should be able to use 17689 as appropriate. For example, we should be able to use
17565 17796
17566 Note that this project failed; there are probably many other details to 17797 Note that this project failed; there are probably many other details to
17567 be implemented that I didn't get to. But don't let that stop you! 17798 be implemented that I didn't get to. But don't let that stop you!
17568 17799
17569 17800
17570 @node Modules for the Basic Displayable Lisp Objects, , Creating a New Console/Device/Frame Type, Consoles; Devices; Frames; Windows 17801
17571 @section Modules for the Basic Displayable Lisp Objects 17802 @node The Redisplay Mechanism, Extents, Window-System Support, Top
17572 @cindex modules for the basic displayable Lisp objects
17573 @cindex displayable Lisp objects, modules for the basic
17574 @cindex Lisp objects, modules for the basic displayable
17575 @cindex objects, modules for the basic displayable Lisp
17576
17577 @example
17578 @file{console-msw.c}
17579 @file{console-msw.h}
17580 @file{console-stream.c}
17581 @file{console-stream.h}
17582 @file{console-tty.c}
17583 @file{console-tty.h}
17584 @file{console-x.c}
17585 @file{console-x.h}
17586 @file{console.c}
17587 @file{console.h}
17588 @end example
17589
17590 These modules implement the @dfn{console} Lisp object type. A console
17591 contains multiple display devices, but only one keyboard and mouse.
17592 Most of the time, a console will contain exactly one device.
17593
17594 @strong{This model may no longer suffice.} The X Window System (at
17595 least) now supports a variety of input devices, including touchscreens
17596 and tablets, as well as the traditional keyboard and mouse, and may even
17597 be able to support multiple instances of a single type of input device
17598 (especially pointing devices) on a single console.
17599
17600 Consoles are the top of a lisp object inclusion hierarchy. Consoles
17601 contain devices, which contain frames, which contain windows.
17602
17603
17604
17605 @example
17606 @file{device-msw.c}
17607 @file{device-tty.c}
17608 @file{device-x.c}
17609 @file{device.c}
17610 @file{device.h}
17611 @end example
17612
17613 These modules implement the @dfn{device} Lisp object type. This
17614 abstracts a particular screen or connection on which frames are
17615 displayed. As with Lisp objects, event interfaces, and other
17616 subsystems, the device code is separated into a generic component that
17617 contains a standardized interface (in the form of a set of methods) onto
17618 particular device types.
17619
17620 The device subsystem defines all the methods and provides method
17621 services for not only device operations but also for the frame, window,
17622 menubar, scrollbar, toolbar, and other displayable-object subsystems.
17623 The reason for this is that all of these subsystems have the same
17624 subtypes (X, TTY, Microsoft Windows, etc.) as devices do.
17625
17626 @strong{This abstraction is probably broken} (as of late 2004), at least
17627 for X consoles, with the advent of the @strong{Xft} library. Xft is a
17628 complete break from the traditional approach to text rendering in the
17629 X11 environment, since fonts are composed of glyphs rendered by
17630 @emph{client-side} code. These glyphs are then transmitted to the
17631 server as sets of trapezoids, and displayed by the @strong{XRender}
17632 extension (where available; the X11 core protocol can also be used, but
17633 this is slow). The XRender extension is especially attractive because
17634 it allows modern image composition techniques to be used to render
17635 antialiased fonts.
17636
17637 By contrast, the traditional approach renders fonts on the server side
17638 as a collection of bitmaps. It is also possible use a @emph{font
17639 server} that knows how to render antialiased fonts, but for some reason
17640 this approach has never caught on.
17641
17642 The problem that this creates for XEmacs is that the traditional (and
17643 still popular) widget sets, the various Athena variants and the Motif
17644 widget set, are based on the server-side rendering model. Thus, even if
17645 XEmacs-specific widgets (such as the basic text window, the Lucid
17646 menubar, and the recently added tab control) can be adapted to render
17647 text via Xft, older widgets (such as buttons and labels) and ``modern''
17648 widgets derived from traditional widgets (the progress gauge) still
17649 expect their font resources to be converted to server-side fonts. Then
17650 text is rendered by calls to the core protocol via Xlib, rather than by
17651 calls to the XRender protocol via Xft.
17652
17653 It's even possible to imagine a situation where a widget is composed of
17654 components which draw their own text (@emph{predefined widgets}) as well
17655 as new components which can draw using more modern methods. Handling
17656 this will either require reworking the Emacs face mechanism to provide a
17657 way to determine whether this widget can use that font, or ways to give
17658 each of several different widgets, even different components of a given
17659 widget, a different face property. This is already an issue, as widgets
17660 generally derive their font from the gui-element face, but this might
17661 not be appropriate for widgets embedded in a buffer.
17662
17663 There seem to be two overall ways to go.
17664
17665 @enumerate
17666 @item
17667 Add face information to the Lucid widget library, and extend the
17668 coverage of that library to device types that aren't supported by it yet
17669 (MS Windows, and maybe TTY).
17670
17671 @item
17672 Create a lighter-weight interface, perhaps an extension of the device
17673 interface, that allows widgets to access face information from the
17674 device it is implemented on.
17675 @end enumerate
17676
17677
17678
17679 @example
17680 @file{frame-msw.c}
17681 @file{frame-tty.c}
17682 @file{frame-x.c}
17683 @file{frame.c}
17684 @file{frame.h}
17685 @end example
17686
17687 Each device contains one or more frames in which objects (e.g. text) are
17688 displayed. A frame corresponds to a window in the window system;
17689 usually this is a top-level window but it could potentially be one of a
17690 number of overlapping child windows within a top-level window, using the
17691 MDI (Multiple Document Interface) protocol in Microsoft Windows or a
17692 similar scheme.
17693
17694 The @file{frame-*} files implement the @dfn{frame} Lisp object type and
17695 provide the generic and device-type-specific operations on frames
17696 (e.g. raising, lowering, resizing, moving, etc.).
17697
17698
17699
17700 @example
17701 @file{window.c}
17702 @file{window.h}
17703 @end example
17704
17705 @cindex window (in Emacs)
17706 @cindex pane
17707 Each frame consists of one or more non-overlapping @dfn{windows} (better
17708 known as @dfn{panes} in standard window-system terminology) in which a
17709 buffer's text can be displayed. Windows can also have scrollbars
17710 displayed around their edges.
17711
17712 @file{window.c} and @file{window.h} implement the @dfn{window} Lisp
17713 object type and provide code to manage windows. Since windows have no
17714 associated resources in the window system (the window system knows only
17715 about the frame; no child windows or anything are used for XEmacs
17716 windows), there is no device-type-specific code here; all of that code
17717 is part of the redisplay mechanism or the code for particular object
17718 types such as scrollbars.
17719
17720
17721 @node The Redisplay Mechanism, Extents, Consoles; Devices; Frames; Windows, Top
17722 @chapter The Redisplay Mechanism 17803 @chapter The Redisplay Mechanism
17723 @cindex redisplay mechanism, the 17804 @cindex redisplay mechanism, the
17724 17805
17725 The redisplay mechanism is one of the most complicated sections of 17806 The redisplay mechanism is one of the most complicated sections of
17726 XEmacs, especially from a conceptual standpoint. This is doubly so 17807 XEmacs, especially from a conceptual standpoint. This is doubly so
28400 @section Discussion -- Garbage Collection 28481 @section Discussion -- Garbage Collection
28401 @cindex discussion, garbage collection 28482 @cindex discussion, garbage collection
28402 @cindex garbage collection, discussion 28483 @cindex garbage collection, discussion
28403 28484
28404 @menu 28485 @menu
28405 * Discussion -- KKCC:: 28486 * Discussion -- KKCC::
28406 * Discussion -- Incremental Collector:: 28487 * Discussion -- Incremental Collector::
28407 * Discussion -- Pure Space:: 28488 * Discussion -- Pure Space::
28408 * Discussion -- Hashtable-Based Marking and Cleanup:: 28489 * Discussion -- Hashtable-Based Marking and Cleanup::
28409 * Discussion -- The Anti-Cons:: 28490 * Discussion -- The Anti-Cons::
28410 @end menu 28491 @end menu
28411 28492