Lucid Emacs version 19.10 This product is an extension of GNU Emacs, known to some as "Lucid Emacs" and to others as "Xemacs". It is based on an early version of Emacs version 19 from the Free Software Foundation, and stems from a collaboration of Lucid, Inc. with SunPro (a division of Sun Microsystems, Inc.) and the University of Illinois. Why Another Version of Emacs? (The Lucid, Inc. Point of View): ============================================================== Lucid's latest product, Energize, is a C/C++ development environment. Rather than invent (and force our users to learn) a new user-interface, we chose to build part of our environment on top of the world's best editor, GNU Emacs. (Though our product is commercial, the work we did on GNU Emacs is free software, and is useful without having to purchase our product.) We needed a version of Emacs with mouse-sensitive regions, multiple fonts, the ability to mark sections of a buffer as read-only, the ability to detect which parts of a buffer has been modified, and many other features. Why Not Epoch or FSF19? ----------------------- For our purposes, the existing version of Epoch was not sufficient; it did not allow us to put arbitrary pixmaps/icons in buffers, `undo' did not restore changes to regions, regions did not overlap and merge their attributes in the way we needed, and several other things. We could have devoted our time to making Epoch do what we needed (and, in fact, we spent some time doing that in 1990) but, since the FSF planned to include Epoch-like features in their version 19, we decided that our efforts would be better spent improving Emacs 19 instead of Epoch. Our original hope was that our changes to Emacs would be incorporated into the "official" v19. However, scheduling conflicts arose, and we found that, given the amount of work still remaining to be done, we didn't have the time or manpower to do the level of coordination that would be necessary to get our changes accepted by the FSF. Consequently, we released our work as a forked branch of Emacs, instead of delaying any longer. Roughly a year after Lucid Emacs 19.0 was released, a beta version of the FSF branch of Emacs 19 was released. The FSF version is better in some areas, and worse in others, as reflects the differing focus of our development efforts. We plan to continue developing and supporting Lucid Emacs, and merging in bug fixes and new features from the FSF branch as appropriate; we do not plan to discard any of the functionality that we implemented which RMS has chosen not to include in his version. Certain elements of Lucid Emacs, or derivatives of them, have been ported to the FSF version. We have not been doing work in this direction, because we feel that Lucid Emacs has a cleaner and more extensible substrate, and that any kind of merger between the two branches would be far easier by merging the FSF changes into our version than the other way around. We have been working closely with the Epoch developers to merge in the remaining Epoch functionality which Lucid Emacs does not yet have. Epoch and Lucid Emacs will soon be one and the same thing. Work is being done on a compatibility package which will allow Epoch 4 code to run in Lemacs with little or no change. (As of 19.8, Lucid Emacs is running a descendant of the Epoch redisplay engine.) Why Another Version of Emacs? (The SunPro Point of View): ========================================================= Emacs 18 has been around for a long, long time. Version 19 was supposed to be the successor to v18 with X support. It was going to be available "real soon" for a long time (some people remember hearing about v19 as early as 1984!), but it never came out. v19 development was going very, very slowly, and from the outside it seemed that it was not moving at all. In the meantime other people gave up waiting for v19 and decided to build their own X-aware Emacsen. The most important of these was probably Epoch, which came from University of Illinois ("UofI") and was based on v18. Around two years ago SunPro decided that we wanted an integrated editor. We contracted with UofI to provide a number of basic enhancements to the functionality in Epoch. UofI initially was planning to deliver this on top of Epoch code. In the meantime (actually some time before we talked with UofI) Lucid had decided that it also wanted to provide an integrated environment with an integrated editor. Lucid decided that the v19 basis was a better one than v18 and thus decided not to use Epoch but instead work with Richard Stallman, the head of the Free Software Foundation and principle author of Emacs, on getting v19 out. At some point Stallman and Lucid parted ways. Lucid kept working and got a v19 out that they called Lucid Emacs 19. After Lucid's v19 came out it became clear to us (UofI and SunPro) that the right thing to do was to push for an integration of both Lucid Emacs and Epoch, and to get the deliverables that we were asking from UofI on top of this integrated platform. Through the last two years, SunPro has been actively supporting this product and has been investing a comparable amount of effort into it as Lucid has. Substantial portions of the current code have originated under the support of SunPro, either directly in SunPro, or in UofI but paid for by us. This code was kept away from Lucid for a while, but later was made available to them. Initially Lucid didn't know that we were supporting UofI, but later we were open about it. Around 6 months ago the SunPro-related code started showing up in Lucid Emacs. This started with the infusion of the Epoch redisplay code. At this moment there is basically no difference in the source trees between what is at UofI, SunPro, or Lucid. All the development sites are in sync. SunPro originally called the integrated product ERA, for "Emacs Rewritten Again". SunPro and Lucid recently came to an agreement to find a name for the product that was not specific to either company. An additional constraint that Lucid placed on the name was that it must contain the word "Emacs" in it -- thus "ERA" is not acceptable. The tentatively agreed-upon name is "XEmacs", and, if all goes according to plan, this is what the product will be called after the release of 19.10. (SunPro is already calling the product XEmacs, but Lucid is still calling it Lucid Emacs.) NOTE: In the rest of the text, we refer to this product as "Lucid Emacs" No Warranty =========== Lucid Emacs is distributed under exactly the same terms as GNU Emacs, and thus has no warranty of any kind. However, if you have received this version of Emacs with Energize, then it is covered by your Energize support contract. If you have received it through some other means, then you may buy a support contract for it from Lucid. Send mail to lucid-info@lucid.com for more information about Lucid Emacs or Energize. What's Different? ================= Unless otherwise noted, this file describes differences between Lucid Emacs version 19.* and GNU Emacs version 18.57. Lucid Emacs *currently* requires an X Window System environment to run, though it will not be much work to make it run on dumb ttys again. We plan to do this eventually. If you would like to volunteer to help, send us mail. Auto-configure support has been added, so it should be fairly easy to compile Lucid Emacs on different systems. If you have any problems or feedback about compiling on your system, please let us know. We have reimplemented the basic input model in a more general way; instead of X input being a special-case of the normal ASCII input stream, Emacs has a concept of "input events", and ASCII characters are a subset of that. The events that Emacs knows about are not X events, but are a generalization of them, so that Emacs can eventually be ported to different window systems. We have reimplemented keymaps so that sequences of events can be stored into them instead of just ASCII codes; it is possible to, for example, bind different commands to each of the chords Control-h, Control-H, Backspace, Control-Backspace, and Super-Shift-Backspace. Key bindings, function key bindings, and mouse bindings live in the same keymaps. Input and display of all ISO-8859-1 characters is supported. You can have multiple X windows ("screens" in lemacs terminology). Our Emacs has objects called "extents" and "faces", which are roughly analogous to Epoch's "buttons," "zones," and "styles." An extent is a region of text (a start position and an end position) and a face is a collection of textual attributes like fonts and colors. Every extent is displayed in some "face", so changing the properties of a face immediately updates the display of all associated extents. Faces can be screen-local: you can have a region of text which displays with completely different attributes when its buffer is viewed from a different X window. The display attributes of faces may be specified either in lisp or through the X resource manager. Pixmaps of arbitrary size can be embedded in a buffer. Variable width fonts work. The height of a line is the height of the tallest font on that line, instead of all lines having the same height. Emacs use the MIT "Xt" toolkit instead of raw Xlib calls, which makes it be a more well-behaved X citizen (and also improves portability). A result of this is that it is possible to include other Xt "Widgets" in the Emacs window. Also, Emacs understands the standard Xt command-line arguments. Emacs understands the X11 "Selection" mechanism; it's possible to define and customize selection converter functions and new selection types from elisp, without having to recompile Emacs. Emacs provides support for ToolTalk on systems that have it. Emacs now supports the Zmacs/Lispm style of region highlighting, where the region between the point and mark is highlighted when in its "active" state. Emacs has a menubar, whose contents are customizable from emacs-lisp. This menubar looks Motif-ish, but does not require Motif. If you already own Motif, however, you can configure Emacs to use a *real* Motif menubar instead. If you have OLIT ("OpenLook Intrinsics"), you can use an OpenWindows-like menubar. Emacs can ask questions using popup dialog boxes. Any command executed from a menu will ask yes/no questions with dialog boxes, while commands executed via the keyboard will use the minibuffer. Emacs has vertical scrollbars. The initial load-path is computed at run-time, instead of at compile-time. This means that if you move the Emacs executable and associated directories to somewhere else, you don't have to recompile anything. You can specify what the title of the Emacs windows and icons should be with the variables `screen-title-format' and `screen-icon-title-format', which have the same syntax as `mode-line-format'. Emacs now supports floating-point numbers. Emacs now knows about timers directly, instead of them being simulated by a subprocess. Emacs understands truenames, and can be configured to notice when you are visiting two names of the same file. See the variables find-file-use-truenames and find-file-compare-truenames. If you're running on a machine with audio hardware, you can specify sound files for Emacs to play instead of the default X beep. See the documentation of the function load-sound-file and the variable sound-alist. An Emacs screen can be placed within an "external client widget" managed by another application. This allows an application to use an Emacs screen as its text pane rather than the standard Text widget that is provided with Motif or Athena. Emacs supports Motif applications, generic Xt (e.g. Athena) applications, and raw XLib applications. Random changes to the emacs-lisp library: (some of this was not written by us, but is included because it's free software and we think it's good stuff) - there is a new optimizing byte-compiler - there is a new abbrev-based mail-alias mechanism - the -*- line can contain local-variable settings - there is a new TAGS package - there is a new VI-emulation mode (evi) - there is a new implementation of Dired - there is a new implementation of Isearch - the VM package for reading mail is provided - the W3 package for browsing the World Wide Web hypertext information system is provided There are many more specifics in the "Miscellaneous Changes" section, below. The online Emacs Manual and Emacs-Lisp Manual are now both relatively up-to-date. Differences between Lucid Emacs 19 and FSF Emacs 19 =================================================== In Lucid Emacs, events are first-class objects. FSF19 represents them as integers, which obscures the differences between a key gesture and the ancient ASCII code used to represent a particular overlapping subset of them. In Lucid Emacs, keymaps are first-class opaque objects. FSF19 represents them as complicated combinations of association lists and vectors. If you use the advertised functional interface to manipulation of keymaps, the same code will work in Lucid Emacs, Emacs 18, and and FSF Emacs 19; if your code depends on the underlying implementation of keymaps, it will not. Lucid Emacs calls a top-level emacs X window a "screen," which is the terminology that Epoch used. FSF 19 calls these "frames." We may adopt the term "frame" as well, but we have not done so yet. Lucid Emacs uses "extents" to represent all non-textual aspects of buffers; FSF 19 uses two distinct objects, "text properties" and "overlays", which divide up the functionality between them. Extents are a superset of the functionality of the two FSF data types. A large subset of the FSF 19 interface to text properties is supported in lemacs (with extents being the underlying representation.) Extents can be made to be copied into strings, and thus restored by kill and yank. Thus, one can specify this behavior on either "extents" or "text properties", whereas in FSF 19 text properties always have this behavior and overlays never do. Here are some more specifics about the Lucid Emacs implementation: The Input Model =============== The fundamental unit of input is an "event" instead of a character. An event is a new data type that contains several pieces of information. There are several kinds of event, and corresponding accessor and utility functions. We tried to abstract them so that they would apply equally well to a number of window systems. key_press_event event_channel A token representing which keyboard generated it. For this kind of event, this is a screen object. (This is for eventual support of multiple displays.) timestamp When it happened key What keysym this is; an integer or a symbol. If this is an integer, it will be in the printing ASCII range: >32 and <127. modifiers Bucky-bits on that key: control, meta, etc. For most keys, Shift is not a bit; that is implicit in the keyboard layout. button_press_event button_release_event event_channel A token representing which mouse generated it. For this kind of event, this is a screen object. timestamp When it happened button What button went down or up. modifiers Bucky-bits on that button: shift, control, meta, etc. x, y Where it was at the button-state-change (in pixels). pointer_motion_event event_channel A token representing which mouse generated it. For this kind of event, this is a screen object. timestamp When it happened x, y Where it was after it moved (in pixels). process_event timestamp When it happened process the emacs "process" object in question timeout_event timestamp Now (really, when the timeout was signalled) function The elisp function to call for this timeout. It is called with one argument, the event. object Some lisp object associated with this timeout, to make it easier to tell them apart. eval_event timestamp When it happened. function An elisp function to call with this event object. object Anything. This kind of event is used internally; sometimes the window system interface would like to inform Emacs of some user action (such as focusing on another screen) but needs that to happen synchronously with the other user input, like keypresses. menu_event timestamp When it happened. function An elisp function to call with this event object. object Anything. This is similar to an eval_event, except that it is generated by selections in the menubar. It is a "command" event, like key and mouse presses (and unlike mouse motion, process output, and enter and leave window hooks.) In many ways, eval_events are not the same as key- or menu-events. magic_event No user-serviceable parts within. This is for things like KeymapNotify and ExposeRegion events and so on that Emacs itself doesn't care about, but which it must do something with for proper interaction with the window system. Magic_events are handled somewhat asynchronously, just like subprocess filters. However, occasionally a magic_event needs to be handled synchronously; in that case, the asynchronous handling of the magic_event will push an eval_event back onto the queue, which will be handled synchronously later. This is why eval_events exist. The function `next-event' blocks and returns one of the above-described event objects. The function `dispatch-event' takes an event and processes it in the appropriate way. For a process-event, dispatch-event calls the process's handler; for a mouse-motion event, the mouse-motion-handler hook is called, and so on. For magic-events, dispatch-event does window-system-dependent things, including calling some non-window-system-dependent hooks: map-screen-hook, unmap-screen-hook, mouse-enter-screen-hook, and mouse-leave-screen-hook. The function `next-command-event' calls `next-event' until it gets a key or button from the user (that is, not a process, motion, timeout, or magic event). If it gets an event that is not a key or button, it calls `dispatch-event' on it immediately and reads another one. The next-command-event function could be implemented in elisp, though it isn't. Generally one should call `next-command-event' instead of `next-event'. read-char calls next-command-event; if it doesn't get an event that can be converted to an ASCII character, it signals an error. Otherwise it returns an integer. The variable `last-command-char' always contains an integer, or nil (if the last read event has no ASCII equivalent, as when it is a mouse-click or a non-ASCII character chord.) The new variable `last-command-event' holds an event object, that could be a non-ASCII character, a button click, a menu selection, etc. The variable `unread-command-char' no longer exists, and has been replaced by `unread-command-event'. With the new event model, it is incorrect for code to do (setq unread-command-char (read-char)), because all user-input can't be represented as ASCII characters. *** This is an incompatible change. Code which sets `unread-command-char' must be updated to use the combination of `next-command-event' and `unread-command-event' instead. The functions `this-command-keys' and `recent-keys' return a vector of event objects, instead of a string of ASCII characters. *** This also is an incompatible change. Almost nothing happens at interrupt level; the SIGIO handler simply sets a flag, and later, the X event queue is scanned for KeyPress events which map to ^G. All redisplay happens in the main thread of the process. We envision the dumb-tty handler functions doing function-key handling at the lowest level. So the terminal-specific code would set up some data structure that would cause the key sequences that some ttys generate for function keys to be converted to 'f1 and so on before next-event saw them. We haven't implemented dumb-tty handling yet, but we will soon. Keymaps ======= Instead of keymaps being alists or obarrays, they are a new primary data type. The only user access to the contents of a keymap is through the existing keymap-manipulation functions, and a new function, map-keymap. *** This means that existing code that manipulates keymaps may need to be changed. One of our goals with the new input and keymap code was to make more character combinations available for binding, besides just ASCII and function keys. We want to be able bind different commands to Control-a and Control-Shift-a; we also want it to be possible for the keys Control-h and Backspace (and Control-M and Return, and Control-I and Tab, etc) to be distinct. One of the most common complaints that new Emacs users have is that backspace is help. The answer is to play around with the keyboard-translate-table, or be lucky enough to have a system administrator who has done this for you already; but if it were possible to bind backspace and C-h to different things, then (under a window manager at least) both backspace and delete would delete a character, and ^H would be help. There's no need to deal with xmodmap, kbd-translate-table, etc. Here are some more examples: suppose you want to bind one function to Tab, and another to Control-Tab. This can't be done if Tab and Control-I are the same thing. What about control keys that have no ASCII equivalent, like Control-< ? One might want that to be bound to set-mark-at-point-min. We want M-C-Backspace to be kill-backward-sexp. But we want M-Backspace to be kill-backward-word. Again, this can't be done if Backspace and C-h are indistinguishable. The user represents keys as a string of ASCII characters (when possible and convenient), or as a vector of event objects, or as a vector of "key description lists", that looks like (control a), or (control meta delete) or (shift f1). The order of the modifier-names is not significant, so (meta control x) and (control meta x) are the same. Define-key knows how to take any of the above representations and store them into a keymap. When Emacs wants to return a key sequence (this-command-keys, recent-keys, keyboard-macros, and read-key-sequence, for example) it returns a vector of event objects. Keyboard macros can also be represented as ASCII strings or as vectors of key description lists. *** This is an incompatible change: code which calls this-command-keys, recent-keys, read-key-sequence, or manipulates keyboard-macros probably needs to be changed so that it no longer assumes that the returned value is a string. Control-Shift-a is specified as (control A), not (control shift a), since A is a two-case character. But for keys that don't have an upper case version, like F1, Backspace, and Escape, you use the (shift backspace) syntax. See the docstring for our version of define-key, reproduced below in the `Changed Functions' section. Note that when the KEYS argument is a string, it has the same semantics as the v18 define-key. Xt Integration ============== The heart of the event loop is implemented in terms of the XtNextEvent, and uses Xt's concept of timeouts and file-descriptor callbacks, eliminating a large amount of system-dependent code (Xt does it for you.) If Emacs is compiled with support for X, we plan to have it use the Xt event loop even when Emacs is not running on an X display (the Xt event loop supports this.) This will make it possible to run Emacs on a dumb tty, and later connect it to one or more X servers. We hope also to make it possible to later connect an existing Emacs process to additional ttys. (Our intent at this point is not to have an Emacs that is being used by multiple people at the same time: it is to make it possible for someone to go home, log in on a dialup line, and connect to the same Emacs process that is running under X in their office without having to recreate their buffer state and so on.) If Emacs is not compiled with support for X, then it will instead use more general code, something like what v18 does; but this way of doing things is a lot more modular. (Linking Emacs with Xt seems to only add about 300k to the executable size, compared with an Emacs linked with Xlib only.) X Selections ============ We have reimplemented X Selection handling to be more general than before. Almost all of it is implemented in emacs-lisp now, so it's possible to define new selection data types without having to recompile Emacs. See the documentation of the variables `selection-converter-alist', `x-lost-selection-hooks', `x-sent-selection-hooks', and the file .../lisp/x11/xselect.el for more specifics. Region Highlighting =================== If the variable `zmacs-regions' is true, then the region between point and mark will be highlighted when "active". Those commands which push a mark (such as C-SPC, and ^X^X) make the region become "active" and thus highlighted. Most commands (all non-motion commands, basically) cause it to become non-highlighted (non-"active"). Commands that operate on the region (such as ^W, ^X^L, etc) only work if the region is in the highlighted state. zmacs-activate-region-hook and zmacs-deactivate-region-hook are run at the appropriate times; under X, zmacs-activate-region-hook makes the X selection be the region between point and mark, thus doing two things at once: making the region and the X selection be the same; and making the region highlight in the same way as the X selection. mark-marker: subr Return this buffer's mark, as a marker object. If `zmacs-regions' is true, then this returns nil unless the region is currently in the active (highlighted) state. With an argument of t, this returns the mark (if there is one) regardless of the active-region state. You should *generally* not use the mark unless the region is active, if the user has expressed a preference for the active-region model. Watch out! Moving this marker changes the mark position. If you set the marker not to point anywhere, the buffer will have no mark. In this way, the primary selection is a fairly transitory entity; but when something is copied to the kill ring, it is made the Clipboard selection. It is also stored into CUT_BUFFER0, for compatibility with X applications that don't understand selections (like Emacs18). *** Compatibility note: if you have code which uses (mark) or (mark-marker), then you need to either: change those calls to (mark t) or (mark-marker t); or simply bind `zmacs-regions' to nil around the call to mark or mark-marker. This is probably the best solution, since it will work in Emacs 18 as well. Menubars and Dialog Boxes ========================= Here is an example of a menubar definition: (defvar default-menubar '(("File" ["Open File..." find-file t] ["Save Buffer" save-buffer t] ["Save Buffer As..." write-file t] ["Revert Buffer" revert-buffer t] "-----" ["Print Buffer" lpr-buffer t] "-----" ["Delete Screen" delete-screen t] ["Kill Buffer..." kill-buffer t] ["Exit Emacs" save-buffers-kill-emacs t] ) ("Edit" ["Undo" advertised-undo t] ["Cut" kill-primary-selection t] ["Copy" copy-primary-selection t] ["Paste" yank-clipboard-selection t] ["Clear" delete-primary-selection t] ) ...)) The first element of each menu item is the string to print on the menu. The second element is the callback function; if it is a symbol, it is invoked with `call-interactively.' If it is a list, it is invoked with `eval'. If the second element is a symbol, then the menu also displays the key that is bound to that command (if any). The third element of the menu items determines whether the item is selectable. It may be t, nil, or a form to evaluate. Also, a hook is run just before a menu is exposed, which can be used to change the value of these slots. For example, there is a hook that makes the "undo" menu item be selectable only in the cases when `advertised-undo' would not signal an error. Menus may have other menus nested within them; they will cascade. There are utility functions for adding items to menus, deleting items, disabling them, etc. The function `popup-menu' takes a menu description and pops it up. The function `popup-dialog-box' takes a dialog-box description and pops it up. Dialog box descriptions look a lot like menu descriptions. The menubar, menu, and dialog-box code is implemented as a library, with an interface which hides the toolkit that implements it. Isearch Changes =============== Isearch has been reimplemented in a different way, adding some new features, and causing a few incompatible changes. - the old isearch-*-char variables are no longer supported. In the old system, one could make ^A mean "repeat the search" by doing something like (setq search-repeat-char ?C-a). In the new system, this is accomplished with (define-key isearch-mode-map "\C-a" 'isearch-repeat-forward) - The advantage of using the normal keymap mechanism for this is that you can bind more than one key to an isearch command: for example, both C-a and C-s could do the same thing inside isearch mode. You can also bind multi-key sequences inside of isearch mode, and bind non-ASCII keys. For example, to use the F1 key to terminate a search: (define-key isearch-mode-map 'f1 'isearch-exit) or to make ``C-c C-c'' terminate a search: (define-key isearch-mode-map "\C-c\C-c" 'isearch-exit) - If isearch is behaving case-insensitively (the default) and you type an upper case character, then the search will become case-sensitive. This can be disabled by setting `search-caps-disable-folding' to nil. - There is a history ring of the strings previously searched for; typing M-p or M-n while searching will cycle through this ring. Typing M-TAB will do completion across the set of items in the history ring. - The ESC key is no longer used to terminate an incremental search. The RET key should be used instead. This change is necessary for it to be possible to bind "meta" characters to isearch commands. Startup Code Changes ==================== The initial X screen is mapped before the user's .emacs file is executed. Without this, there is no way for the user to see any error messages generated by their .emacs file, any windows created by the .emacs file don't show up, and the copyleft notice isn't shown. The default values for load-path, exec-path, lock-directory, and Info-directory-list are not (necessarily) built into Emacs, but are computed at startup time. First, Emacs looks at the directory in which its executable file resides: o If that directory contains subdirectories named "lisp" and "lib-src", then those directories are used as the lisp library and exec directory. o If the parent of the directory in which the emacs executable is located contains "lisp" and "lib-src" subdirectories, then those are used. o If ../lib/lemacs- (starting from the directory in which the emacs executable is located) contains a "lisp" subdirectory and either a "lib-src" subdirectory or a subdirectory, then those are used. o If the emacs executable that was run is a symbolic link, then the link is chased, and the resultant directory is checked as above. (Actually, it doesn't just look for "lisp/", it looks for "lisp/prim/", which reduces the chances of a false positive.) If the lisp directory contains subdirectories, they are added to the default load-path as well. If the site-lisp directory exists and contains subdirectories, they are then added. Subdirectories whose names begin with a dot or a hyphen are not added to the load-path. These heuristics fail if the Emacs binary was copied from the main Emacs tree to some other directory, and links for the lisp directory were not put in. This isn't much of a restriction: either make there be subdirectories (or symbolic links) of the directory of the emacs executable, or make the "installed" emacs executable be a symbolic link to an executable in a more appropriate directory structure. For example, this setup works: /usr/local/lemacs/lemacs* ; The executable. /usr/local/lemacs/lisp/ ; The associated directories. /usr/local/lemacs/etc/ ; Any of the files in this list /usr/local/lemacs/lock/ ; could be symbolic links as well. /usr/local/lemacs/info/ As does this: /usr/local/bin/lemacs -> ../lemacs/src/lemacs-19.8 ; A link... /usr/local/lemacs/src/lemacs-19.8* ; The executable, /usr/local/lemacs/lisp/ ; and the rest of /usr/local/lemacs/etc/ ; the the source /usr/local/lemacs/lock/ ; tree. /usr/local/lemacs/info/ This configuration might be used for a multi-architecture installation; assume that $LOCAL refers to a directory which contains only files specific to a particular architecture (i.e., executables) and $SHARED refers to those files which are not machine specific (i.e., lisp code and documentation.) $LOCAL/bin/lemacs@ -> $LOCAL/lemacs-19.8/lemacs* $LOCAL/lemacs-19.8/lisp@ -> $SHARED/lemacs-19.8/lisp/ $LOCAL/lemacs-19.8/etc@ -> $SHARED/lemacs-19.8/etc/ $LOCAL/lemacs-19.8/info@ -> $SHARED/lemacs-19.8/info/ The following would also work, but the above is probably more attractive: $LOCAL/bin/lemacs* $LOCAL/bin/lisp@ -> $SHARED/lemacs-19.8/lisp/ $LOCAL/bin/etc@ -> $SHARED/lemacs-19.8/etc/ $LOCAL/bin/info@ -> $SHARED/lemacs-19.8/info/ If Emacs can't find the requisite directories, it writes a message like this (or some appropriate subset of it) to stderr: WARNING: couldn't find an obvious default for load-path, exec-directory, and lock-directory, and there were no defaults specified in paths.h when Emacs was built. Perhaps some directories don't exist, or the Emacs executable, /cadillac-th/jwz/somewhere/lemacs is in a strange place? Without both exec-directory and load-path, Emacs will be very broken. Consider making a symbolic link from /cadillac-th/jwz/somewhere/etc to wherever the appropriate Emacs etc/ directory is, and from /cadillac-th/jwz/somewhere/lisp/ to wherever the appropriate Emacs lisp library is. Without lock-directory set, file locking won't work. Consider creating /cadillac-th/jwz/somewhere/lock as a directory or symbolic link for use as the lock directory. The default installation tree is the following: /usr/local/bin/b2m ; ctags ; executables that emacsclient ; should be in etags ; user's path lemacs -> lemacs- ; lemacs ; /usr/local/lib/lemacs/site-lisp /usr/local/lib/lemacs/lock /usr/local/lib/lemacs-/etc ; architecture ind. files /usr/local/lib/lemacs-/info /usr/local/lib/lemacs-/lisp /usr/local/lib/lemacs-/ ; binaries emacs may run X Resources =========== The Emacs resources are generally per-screen. Each Emacs screen can have its own name, or the same name as another, depending on the name passed to the x-create-screen function. You can specify resources for all screens with the syntax Emacs*parameter: value or Emacs*EmacsScreen.parameter: value You can specify resources for a particular screen with the syntax Emacs*SCREEN-NAME.parameter: value To make the default size of all emacs be 80 columns by 55 lines, do this: Emacs*EmacsScreen.geometry: 80x55 To set the geometry of a particular screen named, "foo", do this: Emacs*foo.geometry: 80x55 In particular, do --NOT-- use this syntax: Emacs*geometry: 80x55 One should never use "*geometry" with any X application. It does not say "make the geometry of emacs be 80 columns by 55 lines." It really says, "make emacs and all subwindows thereof be 80x35 in whatever units they care to measure in." In particular, that is both telling the emacs text pane to be 80x55 in characters, and telling the menubar pane to be 80x55 pixels, which is surely not what you want. Generally, all of the interesting resources are on the EmacsScreen widget. However, the `geometry' and `iconic' resources on the unmapped ApplicationShell (the topmost widget, the parent of the WM shell widgets, named `Emacs') are a special case. The simple explanation is, -geometry overrides the resources of only the first screen created, otherwise "Emacs*SCREEN-NAME.geometry" is used. The complicated explanation is: - The -geometry command line option sets the "Emacs.geometry" resource, that is, the geometry of the ApplicationShell. - For the first screen created, the size of the screen is taken from the AppShell if it is specified, otherwise from the geometry of the screen. - For subsequent screens, the order is reversed: first the screen, and then the AppShell. - For the first screen created, the position of the screen is taken from the AppShell ("Emacs.geometry") if it is specified, otherwise from the geometry of the screen. - For subsequent screens, the position is taken only from the screen, and never from the AppShell. This is rather complicated, but it does seem to provide the most intiutive behavior with respect to the default sizes and positions of screens created in various ways. Analagous to -geometry, the -iconic command line option sets the iconic flag of the AppShell ("Emacs.iconic") and always applies to the first screen created regardless of its name. However, it is possible to set the iconic flag on particular screens (by name) by using the "Emacs*SCREEN-NAME.iconic" resource. Emacs screens accept the following resources: iconic (class Iconic): boolean Whether this screen should appear in the iconified state. internalBorderWidth (class InternalBorderWidth): int How many blank pixels to leave between the text and the edge of the window. interline (class Interline): int How many pixels to leave between each line. cursorColor (class CursorColor): color The color of the text cursor. textPointer (class Cursor): cursor-name The cursor to use when the mouse is over text. This resource is used to initialize the variable `x-pointer-shape'. spacePointer (class Cursor): cursor-name The cursor to use when the mouse is over a blank space in a buffer (that is, after the end of a line or after the end-of-file). This resource is used to initialize the variable `x-nontext-pointer-shape'. modePointer (class Cursor): cursor-name The cursor to use when the mouse is over a modeline. This resource is used to initialize the variable `x-mode-pointer-shape'. gcPointer (class Cursor): cursor-name The cursor to display when a garbage-collection is in progress. This resource is used to initialize the variable `x-gc-pointer-shape'. pointerColor (class Foreground): color-name The foreground and background colors of the mouse cursors. These resources are used to initialize the variables `x-pointer-foreground-color' and `x-pointer-background-color'. scrollBarWidth (class ScrollBarWidth): pixels How wide the scrollbars should be; 0 means no scrollbars. You can also use the usual toolkit scrollbar resources for this: "*XmScrollBar.width" (Motif) or "*Scrollbar.thickness" (Athena). The attributes of faces are also per-screen. They may be specified as Emacs*FACE-NAME.parameter: value or Emacs*SCREEN-NAME.FACE-NAME.parameter: value Faces accept the following resources: attributeFont (class AttributeFont): font-name The font of this face. attributeForeground (class AttributeForeground): color-name attributeBackground (class AttributeBackground): color-name The foreground and background colors of this face. attributeBackgroundPixmap (class attributeBackgroundPixmap): file-name The name of an XBM file, to use as a background stipple. attributeUnderline (class AttributeUnderline): boolean Whether text in this face should be underlined. All text is displayed in some face, defaulting to the face named "default". So to set the font of normal text, use "Emacs*default.attributeFont". To set it in the screen named "foo", use "Emacs*foo.default.attributeFont". These are the names of the predefined faces: default Everything inherits from this. highlight This is used to highlight certain extents when the mouse passes over them. bold If this is not specified in the resource database, Emacs tries to find a "bold" version of the font of the "default" face. italic ditto. bold-italic ditto. primary-selection This is the face that mouse-selections are displayed in. isearch This is the face that the matched text being searched for is displayed in. info-node This is the face of info menu items. If unspecified, it is copied from "bold-italic". info-xref This is the face of info cross-references. If unspecified, it is copied from "bold". Other packages might define their own faces; to see a list of all faces, use any of the interactive face-manipulation commands such as `set-face-font') and type `?' when you are prompted for the name of a face. If the bold, italic, and bold-italic faces are not specified in the resource database, then emacs attempts to derive them from the font of the default face. It can only succeed at this if you have specified the default font using the XLFD (X Logical Font Description) format, which looks like *-courier-medium-r-*-*-*-120-*-*-*-*-*-* if you use any of the other, less strict font name formats, some of which look like lucidasanstypewriter-12 and fixed and 9x13 then emacs won't be able to guess the names of the bold and italic versions. All X fonts can be referred to via XLFD-style names, so you should use those forms. See the man pages for X(1), xlsfonts(1), and xfontsel(1). There are several structural widgets between the terminal EmacsScreen widget and the top level ApplicationShell; the exact names and types of these widgets are subject to change in the future, so you should avoid mentioning them in your resource database. The above-mentioned syntaxes should be forward- compatible. As of 19.9, the exact widget hierarchy is as follows: For Motif: ----------- invocation-name "shell" "pane" screen-name x-emacs-application-class "TopLevelShell" "XmMainWindow" "EmacsScreen" For Athena: ----------- invocation-name "shell" "pane" "pane" screen-name x-emacs-application-class "TopLevelShell" "Paned" "Paned" "EmacsScreen" where `invocation-name' is the terminal component of the name of the emacs executable, and `x-emacs-application-class' is generally "Emacs". Since, as you see, the exact widget hierarchy depends on the toolkit in use, and is subject to change in the future, it is best to use wildcards instead of fully specifying the path of the resource you want to st. Here is the hierarchy including the other widgets: Widget Name: Athena Class: Motif Class: ------------ ------------- ------------ lemacs Emacs Emacs shell TopLevelShell TopLevelShell pane Paned XmMainWindow menubar XlwMenu XmMenuBar lower_pane Paned * screen-name EmacsScreen EmacsScreen sb_container Paned XmPanedWindow scrollbar Scrollbar XmScrollBar dialog XtPopupShell XmDialogShell label Label XmLabel button1 ... Command XmPushbutton * Note that the "lower_pane" widget exists only in Athena versions; in Motif versions, both the "menubar" and `screen-name' widgets are children of the "pane". As the menubar is implemented as a widget which is not a part of emacs proper, it does not use the "face" mechanism for specifying fonts and colors: it uses whatever resources are appropriate to the type of widget which is used to implement it. If Emacs was compiled to use only the Motif-lookalike menu widgets, then one way to specify the font of the menubar would be Emacs*menubar*font: *-courier-medium-r-*-*-*-120-*-*-*-*-*-* If the Motif library is being used, then one would have to use Emacs*menubar*fontList: *-courier-medium-r-*-*-*-120-*-*-*-*-*-* because the Motif library uses the "fontList" resource name instead of "font", which has subtly different semantics. The same is true of the scrollbars: they accept whichever resources are appropriate to the toolkit in use. Source Code Highlighting ======================== It's possible to have your buffers "decorated" with fonts or colors indicating syntactic structures (such as strings, comments, function names, "reserved words", etc.) In Lucid Emacs, the preferred way to do this is with font-lock-mode; activate it by adding the following code to your .emacs file: (add-hook 'emacs-lisp-mode-hook 'turn-on-font-lock) (add-hook 'c-mode-hook 'turn-on-font-lock) (add-hook 'c++-mode-hook 'turn-on-font-lock) (add-hook 'dired-mode-hook 'turn-on-font-lock) ...etc... To customize it, see the descriptions of the function `font-lock-mode' and the variables `font-lock-keywords', `c-font-lock-keywords', etc. There exist several other source code highlighting packages, but font-lock does does one thing that most others don't do: highlights as you type new text; and one thing that no others do: bases part of its decoration on the syntax table of the major mode. Font-lock has C-level support to do this efficiently, so it should also be significantly faster than the others. If there's something that another highlighting package does that you can't make font-lock do, let us know. We would prefer to consolidate all of the desired functionality into one package rather than ship several different packages which do essentially the same thing in different ways. Known Problems / TODO List ========================== There are a number of minor redisplay glitches involving the echo area and minibuffer. These will be fixed soon. Many of the `screen-parameters' don't work. I'm not convinced that the screen-parameters/modify-screen-parameters functions are the best interface anyway. The Motif-like menubar that xlwmenu.c defines should use the same resources that real Motif menubars use (as much as possible, anyway.) The `mouse-motion-hook' should be called whenever a buffer scrolls or the sizes of windows change, so that it can correctly frob the mouse-cursor based on the text that the mouse is now over. We need to implement a non-Xt event_stream, based on select() and/or timer signals, so that emacs can be *compiled* without support for X. (Note that this is different than emacs *running* without X.) It should be possible to open emacs screens on multiple X displays and multiple dumb-ttys simultaneously. It should be possible to have a process-filter-function that doesn't get called with a string; rather, the output is simply put in a buffer. This is like a process having both a buffer and a filter-function. This would be a good thing because it would mean that a string need not be consed every time a process generated output, and yet you could be signalled that output had arrived. Miscellaneous Changes ===================== What follows is a semi-automatically generated list of the new functions and variables included with Lucid Emacs, and those functions and variables whose semantics have changed since Emacs 18.57. New Functions: ============== abbreviate-file-name: (filename &optional hack-homedir) Return a version of FILENAME shortened using `directory-abbrev-alist'. See C-h v directory-abbrev-alist RET for more information. If optional argument HACK-HOMEDIR is non-nil, then This also substitutes "~" for the user's home directory. ------------------------------ abs: (arg) Return the absolute value of ARG. ------------------------------ acos: (arg) Return the inverse cosine of ARG. ------------------------------ asin: (arg) Return the inverse sine of ARG. ------------------------------ atan: (arg1 &optional arg2) Return the inverse tangent of ARG. ------------------------------ add-hook: (hook function &optional append) Add to the value of HOOK the function FUNCTION. FUNCTION is not added if already present. FUNCTION is added (if necessary) at the beginning of the hook list unless the optional argument APPEND is non-nil, in which case FUNCTION is added at the end. HOOK should be a symbol, and FUNCTION may be any valid function. If HOOK is void, it is first set to nil. If HOOK's value is a single function, it is changed to a list of functions. ------------------------------ add-menu-item: (menu-path item-name function enabled-p &optional before) Add a menu item to some menu, creating the menu first if necessary. If the named item exists already, it is changed. MENU-PATH identifies the menu under which the new menu item should be inserted. It is a list of strings; for example, ("File") names the top-level "File" menu. ("File" "Foo") names a hypothetical submenu of "File". ITEM-NAME is the string naming the menu item to be added. FUNCTION is the command to invoke when this menu item is selected. If it is a symbol, then it is invoked with `call-interactively', in the same way that functions bound to keys are invoked. If it is a list, then the list is simply evaluated. ENABLED-P controls whether the item is selectable or not. It may be t, nil, or a form to evaluate. It will be evaluated each time the menubar is activated. BEFORE, if provided, is the name of a menu item before which this item should be added, if this item is not on the menu already. If the item is already present, it will not be moved. ------------------------------ add-menu: (menu-path menu-name menu-items &optional before) Add a menu to the menubar or one of its submenus. If the named menu exists already, it is changed. MENU-PATH identifies the menu under which the new menu should be inserted. It is a list of strings; for example, ("File") names the top-level "File" menu. ("File" "Foo") names a hypothetical submenu of "File". If MENU-PATH is nil, then the menu will be added to the menubar itself. MENU-NAME is the string naming the menu to be added. MENU-ITEMS is a list of menu item descriptions. See documentation of variable `current-menubar' for the syntax. BEFORE, if provided, is the name of a menu before which this menu should be added, if this menu is not on its parent already. If the menu is already present, it will not be moved. ------------------------------ add-timeout: (secs function object &optional resignal) SECS is a number of seconds, expressed as an integer or a float. FUNCTION will be called after that many seconds have elapsed, with one argument, the given OBJECT. If the optional RESIGNAL argument is provided, then after this timeout expires, `add-timeout' will automatically be called again with RESIGNAL as the first argument. This function returns an object which is the `id' of this particular timeout. You can pass that object to `disable-timeout' to turn off the timeout before it has been signalled. The number of seconds may be expressed as a floating-point number, in which case some fractional part of a second will be used. Caveat: the usable timeout granularity will vary from system to system. Adding a timeout causes a timeout event to be returned by `next-event', and the function will be invoked by `dispatch-event,' so if emacs is in a tight loop, the function will not be invoked until the next call to sit-for or until the return to top-level (the same is true of process filters.) WARNING: if you are thinking of calling add-timeout from inside of a callback function as a way of resignalling a timeout, think again. There is a race condition. That's why the RESIGNAL argument exists. ------------------------------ allocate-event: () Returns an empty event structure. WARNING, the event object returned may be a reused one; see the function `deallocate-event'. ------------------------------ backtrace-frame: (nframes) Return the function and arguments N frames up from current execution point. If that frame has not evaluated the arguments yet (or is a special form), the value is (nil FUNCTION ARG-FORMS...). If that frame has evaluated its arguments and called its function already, the value is (t FUNCTION ARG-VALUES...). A &rest arg is represented as the tail of the list ARG-VALUES. FUNCTION is whatever was supplied as car of evaluated list, or a lambda expression for macro calls. If N is more than the number of frames, the value is nil. ------------------------------ buffer-list: (&optional screen) Return a list of all existing live buffers. The order is specific to the selected screen; if the optional SCREEN argument is provided, the ordering for that screen is returned instead. If the SCREEN argument is t, then the global (non-screen) ordering is returned instead. ------------------------------ buffer-modified-tick: (&optional buffer) Return BUFFER's tick counter, incremented for each change in text. Each buffer has a tick counter which is incremented each time the text in that buffer is changed. It wraps around occasionally. No argument or nil as argument means use current buffer as BUFFER. ------------------------------ button-press-event-p: (obj) True if the argument is a mouse-button-press event object. ------------------------------ button-release-event-p: (obj) True if the argument is a mouse-button-release event object. ------------------------------ byte-compile-and-load-file: (filename) Compile a file of Lisp code named FILENAME into a file of byte code, and then load it. The output file's name is made by appending "c" to the end of FILENAME. ------------------------------ byte-compile-buffer: (&optional buffer) Byte-compile and evaluate contents of BUFFER (default: the current buffer). ------------------------------ byte-compiler-options: (&rest args) Set some compilation-parameters for this file. This will affect only the file in which it appears; this does nothing when evaluated, and when loaded from a .el file. Each argument to this macro must be a list of a key and a value. Keys: Values: Corresponding variable: verbose t, nil byte-compile-verbose optimize t, nil, source, byte byte-compile-optimize warnings list of warnings byte-compile-warnings Legal elements: (callargs redefine free-vars unresolved) file-format emacs18, emacs19 byte-compile-emacs18-compatibility new-bytecodes t, nil byte-compile-generate-emacs19-bytecodes For example, this might appear at the top of a source file: (byte-compiler-options (optimize t) (warnings (- free-vars)) ; Don't warn about free variables (file-format emacs19)) ------------------------------ case-table-p: (table) Return t iff ARG is a case table. See `set-case-table' for more information on these data structures. ------------------------------ ceiling: (arg) Return the smallest integer no less than ARG. (Round toward +inf.) ------------------------------ character-to-event: (ch &optional event) Converts a numeric ASCII value to an event structure, replete with bucky bits. The character is the first argument, and the event to fill in is the second. This function contains knowledge about what the codes ``mean'' -- for example, the number 9 is converted to the character ``Tab'', not the distinct character ``Control-I''. If the optional second argument is an event, it is modified; otherwise, a new event object is created. Beware that character-to-event and event-to-character are not strictly inverse functions, since events contain much more information than the ASCII character set can encode. ------------------------------ clrhash: (table) Flush TABLE. ------------------------------ compile-defun: () Compile and evaluate the current top-level form. Print the result in the minibuffer. With argument, insert value in current buffer after the form. ------------------------------ compiled-function-arglist: (function) Returns the argument list of the compiled-function object. ------------------------------ compiled-function-constants: (function) Returns the constants vector of the compiled-function object. ------------------------------ compiled-function-instructions: (function) Returns the byte-opcode string of the compiled-function object. ------------------------------ compiled-function-interactive: (function) Returns the interactive spec of the compiled-function object, or nil. ------------------------------ compiled-function-p: (obj) T if OBJECT is a byte-compiled function object. ------------------------------ compiled-function-stack-depth: (function) Returns the max stack depth of the compiled-function object. ------------------------------ conx: () Generate some random sentences in the *conx* buffer. Output will be continuously generated until you type ^G. Before running this function, you must snarf some text into the CONX database with the M-x conx-buffer or M-x conx-region commands. ------------------------------ copy-event: (event1 &optional event2) Make a copy of the given event object. If a second argument is given, the first event is copied into the second and the second is returned. If the second argument is not supplied (or is nil) then a new event will be made as with `allocate-event.' See also the function `deallocate-event'. ------------------------------ copy-extent: (extent &optional buffer) Make a copy of EXTENT. It is initially detached. The optional BUFFER argument defaults to EXTENT's buffer. ------------------------------ copy-face: (old-face new-name &optional screen) Defines and returns a new face which is a copy of an existing one, or makes an already-existing face be exactly like another. ------------------------------ copy-tree: (arg &optional vecp) Return a copy of a list and substructures. The argument is copied, and any lists contained within it are copied recursively. Circularities and shared substructures are not preserved. Second arg VECP causes vectors to be copied, too. Strings are not copied. ------------------------------ cos: (arg) Return the cosine of ARG. ------------------------------ cosh: (arg) Return the hyperbolic cosine of ARG. ------------------------------ colorize-pixmap: (pixmap foreground background) Make the pixmap be displayed in the given colors. Pixmaps come in two varieties: bitmaps, which are 1 bit deep which are rendered in the prevailing foreground and background colors; and pixmaps, which are of arbitrary depth (including 1) and which have the colors explicitly specified. This function converts a bitmap to a pixmap. If the pixmap was a pixmap already, nothing is done (and nil is returned.) Otherwise t is returned. ------------------------------ current-case-table: () Return the case table of the current buffer. ------------------------------ current-time: () Return the current time, as the number of seconds since 12:00 AM January 1970. The time is returned as a list of three integers. The first has the most significant 16 bits of the seconds, while the second has the least significant 16 bits. The third integer gives the microsecond count. The microsecond count is zero on systems that do not provide resolution finer than a second. ------------------------------ deallocate-event: (event) Allow the given event structure to be reused. You MUST NOT use this event object after calling this function with it. You will lose. It is not necessary to call this function, as event objects are garbage- collected like all other objects; however, it may be more efficient to explicitly deallocate events when you are sure that that is safe. ------------------------------ deiconify-screen: (screen) Open (de-iconify) the iconified screen SCREEN. ------------------------------ delete-extent: (extent) Remove EXTENT from its buffer; this does not modify the buffer's text, only its display properties. The extent cannot be used thereafter. ------------------------------ delete-menu-item: (path) Remove the named menu item from the menu hierarchy. PATH is a list of strings which identify the position of the menu item in the menu hierarchy. ("File" "Save") means the menu item called "Save" under the toplevel "File" menu. ("Menu" "Foo" "Item") means the menu item called "Item" under the "Foo" submenu of "Menu". ------------------------------ delete-screen: (&optional screen) Delete SCREEN, permanently eliminating it from use. Default is current screen. A screen may not be deleted if its minibuffer is used by other screens. ------------------------------ delete-window: (&optional window) Remove WINDOW from the display. Default is selected window. If window is the only one on the screen, the screen is destroyed. ------------------------------ detach-extent: (extent_obj) Remove EXTENT from its buffer in such a way that it can be re-inserted. An extent is also detached when all of its characters are all killed by a deletion. Extents which have the `duplicable' attribute are tracked by the undo mechanism. Detachment via `detach-extent' and string deletion is recorded, as is attachment via `insert-extent', `update-extent', and string insertion. Extent motion, face changes, and attachment via `make-extent' are not recorded. This means that extent changes which are to be undo-able must be performed by character editing, or by insertion and detachment of duplicable extents. ------------------------------ disable-menu-item: (path) Make the named menu item be unselectable. PATH is a list of strings which identify the position of the menu item in the menu hierarchy. ("File" "Save") means the menu item called "Save" under the toplevel "File" menu. ("Menu" "Foo" "Item") means the menu item called "Item" under the "Foo" submenu of "Menu". ------------------------------ disable-timeout: (id) Given a timeout id number as returned by `add-timeout', this function will cause that timeout to not be signalled if it hasn't been already. ------------------------------ dispatch-event: (event) Given an event object returned by next-event, execute it. ------------------------------ enable-menu-item: (path) Make the named menu item be selectable. PATH is a list of strings which identify the position of the menu item in the menu hierarchy. ("File" "Save") means the menu item called "Save" under the toplevel "File" menu. ("Menu" "Foo" "Item") means the menu item called "Item" under the "Foo" submenu of "Menu". ------------------------------ enqueue-eval-event: (function object) Add an eval event to the back of the queue. The eval-event will be the next event read after all pending events. ------------------------------ eval-and-compile: (&rest body) Like `progn', but evaluates the body at compile time and at load time. ------------------------------ eval-event-p: (obj) True if the argument is an `eval' or `menu' event object. ------------------------------ eval-when-compile: () Like `progn', but evaluates the body at compile time. The result of the body appears to the compiler as a quoted constant. ------------------------------ event-button: (event) Returns the button-number of the given mouse-button-press event. ------------------------------ event-function: (event) Returns the callback function of the given timeout, menu, or eval event. ------------------------------ event-glyph: (event) If the given mouse-motion, button-press, or button-release event happened on top of a glyph, this returns it; else nil. ------------------------------ event-key: (event) Returns the KeySym of the given key-press event. This will be the ASCII code of a printing character, or a symbol. ------------------------------ event-modifier-bits: (event) Returns a number representing the modifier keys which were down when the given mouse or keyboard event was produced. See also the function event-modifiers. ------------------------------ event-modifiers: (event) Returns a list of symbols, the names of the modifier keys which were down when the given mouse or keyboard event was produced. See also the function event-modifier-bits. ------------------------------ event-object: (event) Returns the callback function argument of the given timeout, menu, or eval event. ------------------------------ event-point: (event) Returns the character position of the given mouse-motion, button-press, or button-release event. If the event did not occur over a window, or did not occur over text, then this returns nil. Otherwise, it returns an index into the buffer visible in the event's window. ------------------------------ event-process: (event) Returns the process of the given proces-output event. ------------------------------ event-screen: (event) Given a mouse motion, button press, or button release event, return the screen on which that event occurred. This will be nil for non-mouse events. ------------------------------ event-timestamp: (event) Returns the timestamp of the given event object. ------------------------------ event-to-character: (event &optional allow-extra-modifiers allow-meta allow-non-ascii) Returns the closest ASCII approximation to the given event object. If the event isn't a keypress, this returns nil. If the ALLOW-EXTRA-MODIFIERS argument is non-nil, then this is lenient in its translation; it will ignore modifier keys other than control and meta, and will ignore the shift modifier on those characters which have no shifted ASCII equivalent (Control-Shift-A for example, will be mapped to the same ASCII code as Control-A.) If the ALLOW-META argument is non-nil, then the Meta modifier will be represented by turning on the high bit of the byte returned; otherwise, nil will be returned for events containing the Meta modifier. If the ALLOW-NON-ASCII argument is non-nil, then characters which are present in the prevailing character set (see the `character-set-property' variable) will be returned as their code in that character set, instead of the return value being restricted to ASCII. Note that specifying both ALLOW-META and ALLOW-NON-ASCII is ambiguous, as both use the high bit; `M-x' and `oslash' will be indistinguishable. ------------------------------ event-window: (event) Given a mouse motion, button press, or button release event, compute and return the window on which that event occurred. This may be nil if the event did not occur in an emacs window (in the border or modeline.) ------------------------------ event-x: (event) Returns the X position of the given mouse-motion, button-press, or button-release event in characters. ------------------------------ event-x-pixel: (event) Returns the X position of the given mouse-motion, button-press, or button-release event in pixels. ------------------------------ event-y: (event) Returns the Y position of the given mouse-motion, button-press, or button-release event in characters. ------------------------------ event-y-pixel: (event) Returns the Y position of the given mouse-motion, button-press, or button-release event in pixels. ------------------------------ eventp: (obj) True if the argument is an event object. ------------------------------ events-to-keys: (events &optional no-mice) Given a vector of event objects, returns a vector of key descriptors, or a string (if they all fit in the ASCII range.) Optional arg NO-MICE means that button events are not allowed. ------------------------------ exp: (arg) Return the exponential base e of ARG. ------------------------------ expt: (x y) Return the exponential x ** y. ------------------------------ extent-at: (pos &optional buffer property before) Find "smallest" extent at POS in BUFFER having PROPERTY set. BUFFER defaults to the current buffer. PROPERTY defaults to nil, meaning that any extent will do. Properties are attached to extents with `set-extent-property', which see. Returns nil if there is no matching extent at POS. If the fourth argument BEFORE is not nil, it must be an extent; any returned extent will precede that extent. This feature allows `extent-at' to be used by a loop over extents. ------------------------------ extent-begin-glyph: (extent) Return the glyph object displayed at the beginning of EXTENT. Returns nil, a pixmap, or a string. ------------------------------ extent-buffer: (extent_obj) Return buffer of EXTENT. ------------------------------ extent-end-glyph: (extent) Return the glyph object displayed at the end of EXTENT. Returns nil, a pixmap, or a string. ------------------------------ extent-end-position: (extent) Return first position after EXTENT. ------------------------------ extent-face: (extent) Returns the name of the face in which EXTENT is displayed, or nil if the extent's face is unspecified. ------------------------------ extent-in-region-p: (extent &optional from to closed-end) Whether map-extents would visit EXTENT when called with these args. ------------------------------ extent-length: (extent) Return length of EXTENT in characters. ------------------------------ extent-priority: (extent) Returns the display priority of EXTENT; see `set-extent-priority'. ------------------------------ extent-properties: (extent) Return a property list of the attributes of the given extent. Do not modify this list; use `set-extent-property' instead. ------------------------------ extent-property: (extent property) Returns the extent's value of the given property. See `set-extent-property' for builtin property names. ------------------------------ extent-start-position: (extent) Return start position of EXTENT. ------------------------------ extentp: (extent) T if OBJECT is an extent.. ------------------------------ face-background: (face &optional screen) Returns the background color name of the given face, or nil if unspecified. ------------------------------ face-background-pixmap: (face &optional screen) Returns the background pixmap of the given face, or nil if unspecified. ------------------------------ face-differs-from-default-p: (face &optional screen) True if the given face will display differently from the default face. A face is considered to be ``the same'' as the default face if it is actually specified in the same way (equivalent fonts, etc) or if it is fully unspecified, and thus will inherit the attributes of any face it is displayed on top of. ------------------------------ face-equal: (face1 face2 &optional screen) True if the given faces will display in the the same way. ------------------------------ face-font: (face &optional screen) Returns the font of the given face, or nil if it is unspecified. ------------------------------ face-font-name: (face &optional screen) Returns the font name of the given face, or nil if it is unspecified. ------------------------------ face-foreground: (face &optional screen) Returns the foreground color of the given face, or nil if unspecified. ------------------------------ face-id: (face) Returns the internal ID number of the given face. ------------------------------ face-underline-p: (face &optional screen) Returns whether the given face is underlined. ------------------------------ fceiling: (arg) Return the smallest integer no less than ARG, as a float. (Round toward +inf.) ------------------------------ ffloor: (arg) Return the largest integer no greater than ARG, as a float. (Round towards -inf.) ------------------------------ font-name: (font) Returns the name used to allocate the given font. ------------------------------ font-truename: (font) Returns the canonical name of the given font. Font names are patterns which may match any number of fonts, of which the first found is used. This returns an unambiguous name for that font (but not necessarily its only unambiguous name.) ------------------------------ fontp: (obj) Whether the given object is a font. ------------------------------ fround: (arg) Return the nearest integer to ARG, as a float. ------------------------------ ftruncate: (arg) Truncate a floating point number to an integral float value. Rounds the value toward zero. ------------------------------ file-executable-p: (filename) Return t if FILENAME can be executed by you. For a directory, this means you can access files in that directory. ------------------------------ find-face: (name &optional screen) Retrieve the face of the given name. If NAME is a symbol and SCREEN is provided, the face is looked up on that screen; otherwise, the selected screen is used. If there is no such face, returns nil. If SCREEN is the symbol t, then the global, non-screen face is returned. If NAME is already a face, it is simply returned. ------------------------------ find-file-other-screen: (filename) Edit file FILENAME, in a newly-created screen. ------------------------------ find-file-read-only-other-screen: (filename) Edit file FILENAME in another screen but don't allow changes. Like C-x 5 f but marks buffer as read-only. Use M-x toggle-read-only to permit editing. ------------------------------ float: (arg) Return the floating point number equal to ARG. ------------------------------ floor: (arg) Return the largest integer no greater than ARG. (Round towards -inf.) ------------------------------ force-highlight-extent: (extent &optional flag) Highlight any EXTENT if FLAG is not nil, else unhighlight it. This is the same as `highlight-extent', except that it will work even on extents without the 'highlight property. ------------------------------ forward-comment: (n) Move forward across up to N comments. If N is negative, move backward. Stop scanning if we find something other than a comment or whitespace. Set point to where scanning stops. If N comments are found as expected, with nothing except whitespace between them, return t; otherwise return nil. Point is set in either case. ------------------------------ get-face: (name &optional screen) Retrieve the face of the given name. If NAME is a symbol and SCREEN is provided, the face is looked up on that screen; otherwise, the selected screen is used. If there is no such face, an error is signalled. See also `find-face'. If SCREEN is the symbol t, then the global, non-screen face is returned. If NAME is already a face, it is simply returned. ------------------------------ get-screen-for-buffer: (buffer &optional not-this-window-p on-screen) Select and return a screen in which to display BUFFER. Normally, the buffer will simply be displayed in the current screen. But if the symbol naming the major-mode of the buffer has a 'screen-name property (which should be a symbol), then the buffer will be displayed in a screen of that name. If there is no screen of that name, then one is created. If the major-mode doesn't have a 'screen-name property, then the screen named by `get-screen-for-buffer-default-screen-name' will be used. If that is nil (the default) then the currently selected screen will used. If the screen-name symbol has an 'instance-limit property (an integer) then each time a buffer of the mode in question is displayed, a new screen with that name will be created, until there are `instance-limit' of them. If instance-limit is 0, then a new screen will be created each time. If a buffer is already displayed in a screen, then `instance-limit' is ignored, and that screen is used. If the screen-name symbol has a 'screen-defaults property, then that is prepended to the `screen-default-alist' when creating a screen for the first time. This function may be used as the value of `pre-display-buffer-function', to cause the display-buffer function and its callers to exhibit the above behavior. ------------------------------ getf: (plist prop &optional defalt) Search PROPLIST for property PROPNAME; return its value or DEFAULT. PROPLIST is a list of the sort returned by `symbol-plist'. ------------------------------ gethash: (key table &optional default) Find hash value for KEY in TABLE. If there is no corresponding value, return DEFAULT (default nil) ------------------------------ hashtable-fullness: (table) Returns number of entries in TABLE. ------------------------------ hashtablep: (obj) Returns t if OBJ is a hashtable, else nil. ------------------------------ highlight-extent: (extent &optional flag) If EXTENT is `highlightable' (has the 'highlight property) then highlight it (by using merging it with 'highlight face.) If FLAG is nil, then unhighlight it instead. ------------------------------ iconify-screen: (screen) Make the screen SCREEN into an icon, if the window manager supports icons. ------------------------------ invert-face: (face &optional screen) Swap the foreground and background colors of the given face. If the face doesn't specify both foreground and background, then its foreground and background are set to the background and foreground of the default face. ------------------------------ key-press-event-p: (obj) True if the argument is a key-press event object. ------------------------------ keymap-default-binding: (keymap) Returns the default binding of KEYMAP, or `nil' if it has none. The default-binding is returned when no other binding for a key-sequence is found in the keymap. If a keymap has a non-nil default-binding, neither the keymap's parents nor the current global map are searched for key bindings. ------------------------------ keymap-parents: (keymap) Returns the `parent' keymaps of the given keymap, or nil. The parents of a keymap are searched for keybindings when a key sequence isn't bound in this one. `(current-global-map)' is the default parent of all keymaps. ------------------------------ keymapp: (object) Return t if ARG is a keymap object. ------------------------------ list-faces: () Returns a list of the names of all of the defined faces. ------------------------------ live-screen-p: (object) Return non-nil if OBJECT is a screen which has not been deleted. Value is nil if OBJECT is not a live screen. If object is a live screen, the return value indicates what sort of output device it is displayed on. Value is t for a termcap screen (a character-only terminal), `x' for an Emacs screen being displayed in an X window. ------------------------------ load-average: () Return list of 1 minute, 5 minute and 15 minute load averages. Each of the three load averages is multiplied by 100, then converted to integer. If the 5-minute or 15-minute load averages are not available, return a shortened list, containing only those averages which are available. On most systems, this won't work unless the emacs executable is installed as setgid kmem (assuming that /dev/kmem is in the group kmem.) ------------------------------ load-default-sounds: () Load and install some sound files as beep-types. This only works if you're on display 0 of a Sun SparcStation, SGI machine, or HP9000s700. ------------------------------ load-sound-file: (filename sound-name &optional volume) Read in an audio-file and add it to the sound-alist. ------------------------------ locate-library: (library &optional nosuffix) Show the full path name of Emacs library LIBRARY. This command searches the directories in `load-path' like `M-x load-library' to find the file that `M-x load-library RET LIBRARY RET' would load. Optional second arg NOSUFFIX non-nil means don't add suffixes `.elc' or `.el' to the specified name LIBRARY (a la calling `load' instead of `load-library'). ------------------------------ log: (arg1 &optional arg2) Return the natural logarithm of ARG. With two arguments, return the logarithm of ARG to the base ARG2. ------------------------------ log10: (arg) Return the logarithm base 10 of ARG. ------------------------------ make-cursor: (name &optional fg bg screen) Creates a new `cursor' object of the specified name. The optional second and third arguments are the foreground and background colors. They may be color name strings or `pixel' objects. The optional fourth argument is the screen on which to allocate the cursor (in case some screens are running on different X servers.) This allocates a new cursor in the X server, and signals an error if the cursor is unknown or cannot be allocated. A cursor name can take many different forms. It can be: - any of the standard cursor names from appendix B of the Xlib manual (also known as the file ) minus the XC_ prefix; - the name of a font, and glyph index into it of the form "FONT fontname index [[mask-font] mask-index]"; - the name of a bitmap or pixmap file; - or a pixmap object, as returned by `make-pixmap'. If it is a pixmap or pixmap file, and that pixmap comes with a mask, then that mask will be used. If it is a pixmap, it must have only one plane, since X cursors may only have two colors. If it is a pixmap file, then the file will be read in monochrome. If it is a bitmap file, and if a bitmap file whose name is the name of the cursor with "msk" or "Mask" appended exists, then that second bitmap will be used as the mask. For example, a pair of files might be named "cursor.xbm" and "cursor.xbmmsk". The returned object is a normal, first-class lisp object. The way you `deallocate' the cursor is the way you deallocate any other lisp object: you drop all pointers to it and allow it to be garbage collected. When these objects are GCed, the underlying X data is deallocated as well. ------------------------------ make-directory: (dir) Create the directory DIR and any nonexistent parent dirs. ------------------------------ make-extent: (from to &optional buffer) Make extent for range [FROM, TO) in BUFFER -- BUFFER defaults to current buffer. Insertions at point TO will be outside of the extent; insertions at FROM will be inside the extent (and the extent will grow.) The extent is initially detached if if both FROM and TO are null, and in this case BUFFER defaults to NIL, meaning the extent is in no buffer. The initial attributes are (end-open), meaning that start and end points behave like markers. ------------------------------ make-face: (name) Defines and returns a new FACE on all screens. You can modify the font, color, etc of this face with the set-face- functions. If the face already exists, it is unmodified. ------------------------------ make-face-bold: (face &optional screen) Make the font of the given face be bold, if possible. Returns nil on failure. ------------------------------ make-face-bold-italic: (face &optional screen) Make the font of the given face be bold and italic, if possible. Returns nil on failure. ------------------------------ make-face-italic: (face &optional screen) Make the font of the given face be italic, if possible. Returns nil on failure. ------------------------------ make-face-larger: (face &optional screen) Make the font of the given face be larger, if possible. Returns nil on failure. ------------------------------ make-face-smaller: (face &optional screen) Make the font of the given face be smaller, if possible. Returns nil on failure. ------------------------------ make-face-unbold: (face &optional screen) Make the font of the given face be non-bold, if possible. Returns nil on failure. ------------------------------ make-face-unitalic: (face &optional screen) Make the font of the given face be non-italic, if possible. Returns nil on failure. ------------------------------ make-font: (name &optional screen) Creates a new `font' object of the specified name. The optional second argument is the screen on which to allocate the font (in case some screens are running on different X servers.) This allocates a font in the X server, and signals an error if the font is unknown or cannot be allocated. The returned object is a normal, first-class lisp object. The way you `deallocate' the font is the way you deallocate any other lisp object: you drop all pointers to it and allow it to be garbage collected. When these objects are GCed, the underlying X data is deallocated as well. ------------------------------ make-hashtable: (size) Make a hashtable of initial size SIZE. ------------------------------ make-keymap: () Construct and return a new keymap object. All entries in it are nil, meaning "command undefined". ------------------------------ make-obsolete: (fn new) Make the byte-compiler warn that FUNCTION is obsolete. The warning will say that NEW should be used instead. If NEW is a string, that is the `use instead' message. ------------------------------ make-obsolete-variable: (var new) Make the byte-compiler warn that VARIABLE is obsolete, and NEW should be used instead. If NEW is a string, then that is the `use instead' message. ------------------------------ make-pixel: (name &optional screen) Creates a new `pixel' object of the specified color. The optional second argument is the screen on which to allocate the pixel (in case some screens are running on different X servers.) This allocates a new color cell in the X server, and signals an error if the color is unknown or cannot be allocated. The returned object is a normal, first-class lisp object. The way you `deallocate' the color is the way you deallocate any other lisp object: you drop all pointers to it and allow it to be garbage collected. When these objects are GCed, the underlying X data is deallocated as well. ------------------------------ make-pixmap: (name &optional screen) Loads a new `pixmap' object from the specified file. The file should be in `XBM' or `XPM' format. If the XBMLANGPATH environment variable is set, it will be searched for matching files. Next, the directories listed in the `x-bitmap-file-path' variable will be searched (this variable is initialized from the "*bitmapFilePath" resource.) The file argument may also be a list of the form (width height data) where width and height are the size in pixels, and data is a string, containing the raw bits of the bitmap. (Bitmaps specified this way can only be one bit deep.) If compiled with support for XPM, the file argument may also be a string which is the contents of an XPM file (that is, a string beginning with the characters "/* XPM */"; see the XPM documentation.) The optional second argument is the screen on which to allocate the pixmap (in case some screens are running on different X servers.) This allocates a new Pixmap in the X server, and signals an error if the file can't be found, or the Pixmap cannot be allocated. The returned object is a normal, first-class lisp object. The way you `deallocate' the pixmap is the way you deallocate any other lisp object: you drop all pointers to it and allow it to be garbage collected. When these objects are GCed, the underlying X data is deallocated as well. ------------------------------ make-screen: (&optional parameters) Create a new screen, displaying the current buffer. Optional argument PARAMETERS is an alist of parameters for the new screen. Specifically, PARAMETERS is a list of pairs, each having one of the following forms: (name . STRING) - The screen should be named STRING. (height . NUMBER) - The screen should be NUMBER text lines high. (width . NUMBER) - The screen should be NUMBER columns wide. The documentation for the function `x-create-screen' describes additional screen parameters that Emacs recognizes for X window screens. ------------------------------ make-screen-invisible: (screen) Unconditionally removes screen from the display (assuming it is an X-window). If what you want to do is iconify the screen (if the window manager uses icons) then you should call `iconify-screen' instead. ------------------------------ make-screen-visible: (screen) Make the screen SCREEN visible (assuming it is an X-window). Also raises the screen so that nothing obscures it. ------------------------------ make-temp-name: (prefix) Generate temporary file name (string) starting with PREFIX (a string). The Emacs process number forms part of the result, so there is no danger of generating a name being used by another process. ------------------------------ make-weak-hashtable: (size) Make a weak hashtable of initial size SIZE. A weak hashtable is one whose pointers do not count as GC referents: if the only remaining pointer to an object is in a weak hash table, then that object will be removed from the table, and collected. A non-weak hash table (or any other pointer) would prevent the object from being collected. ------------------------------ map-extents: (function &optional buffer from to maparg closed-end) Map FUNCTION over the extents which overlap region in BUFFER, starting at FROM and ending at TO. FUNCTION is called with the arguments (extent, MAPARG). The arguments FROM, TO, MAPARG, and BUFFER default to the beginning of BUFFER, the end of BUFFER, nil, and (current-buffer), respectively. MAP-EXTENTS returns the first non-null result produced by FUNCTION, and no more calls to FUNCTION are made after it returns non-null. If BUFFER is an extent, FROM and TO default to the extent's endpoints, and the mapping omits that extent and its predecessors. This feature supports restarting a loop based on `map-extents'. ------------------------------ map-extent-children: (function &optional buffer from to maparg closed_end) Map FUNCTION over the extents in the region from FROM to TO. FUNCTION is called with arguments (extent, MAPARG). The arguments are the same as for `map-extents', but this function differs in that it only visits extents which start in the given region, and also in that, after visiting an extent E, it skips all other extents which start inside E but end before E's end. Thus, this function may be used to walk a tree of extents in a buffer: (defun walk-extents (buffer &optional ignore) (map-extent-children 'walk-extents buffer)) ------------------------------ map-keymap: (function keymap &optional sort_first) Apply FUNCTION to each element of KEYMAP. FUNCTION will be called with two arguments: a key-description list, and the binding. The order in which the elements of the keymap are passed to the function is unspecified. If the function inserts new elements into the keymap, it may or may not be called with them later. No element of the keymap will ever be passed to the function more than once. The function will not be called on elements of this keymap's parent (see the function `keymap-parents') or upon keymaps which are contained within this keymap (multi-character definitions). It will be called on "meta" characters since they are not really two-character sequences. If the optional third argument SORT-FIRST is non-nil, then the elements of the keymap will be passed to the mapper function in a canonical order. Otherwise, they will be passed in hash (that is, random) order, which is faster. ------------------------------ maphash: (function table) Map FUNCTION over entries in TABLE, calling it with two args, each key and value in the table. ------------------------------ mark-bob: (&optional arg) bound to C-< Push a mark at the beginning of the buffer; leave point where it is. With arg N, push mark N/10 of the way from the true beginning. ------------------------------ mark-eob: (&optional arg) bound to C-> Push a mark at the end of the buffer; leave point where it is. With arg N, push mark N/10 of the way from the true end. ------------------------------ member: (elt list) Return non-nil if ELT is an element of LIST. Comparison done with EQUAL. The value is actually the tail of LIST whose car is ELT. ------------------------------ menu-event-p: (obj) True if the argument is a menu event object. ------------------------------ modify-screen-parameters: (screen alist) Modify the parameters of screen SCREEN according to ALIST. ALIST is an alist of parameters to change and their new values. Each element of ALIST has the form (PARM . VALUE), where PARM is a symbol. The meaningful PARMs depend on the kind of screen; undefined PARMs are ignored. ------------------------------ motion-event-p: (obj) True if the argument is a mouse-motion event object. ------------------------------ mouse-del-char: (event) Delete the char pointed to by the mouse. ------------------------------ mouse-delete-window: () Delete the Emacs window the mouse is on. ------------------------------ mouse-drag-modeline: (event) Resize the window by dragging the modeline. This should be bound to a mouse button in `mode-line-map'. ------------------------------ mouse-keep-one-window: () Select Emacs window mouse is on, then kill all other Emacs windows. ------------------------------ mouse-kill-line: (event) Kill the line pointed to by the mouse. ------------------------------ mouse-line-length: (event) Print the length of the line indicated by the pointer. ------------------------------ mouse-scroll: (event) Scroll point to the mouse position. ------------------------------ mouse-select: () Select Emacs window the mouse is on. ------------------------------ mouse-select-and-split: () Select Emacs window mouse is on, then split it vertically in half. ------------------------------ mouse-set-mark: (event) Select Emacs window mouse is on, and set mark at mouse position. Display cursor at that position for a second. ------------------------------ mouse-set-point: (event) Select Emacs window mouse is on, and move point to mouse position. ------------------------------ mouse-track: (event) Make a selection with the mouse. This should be bound to a mouse button. If you click-and-drag, the selection will be set to the region between the point of the initial click and the point at which you release the button. These positions need not be ordered. If you click-and-release without moving the mouse, then the point is moved, and the selection is disowned (there will be no selection owner.) If you double-click, the selection will extend by symbols instead of by characters. If you triple-click, the selection will extend by lines. If you drag the mouse off the top or bottom of the window, you can select pieces of text which are larger than the visible part of the buffer; the buffer will scroll as necessary. The selected text becomes the current X Selection, and is also copied to the top of the kill ring. The point will be left at the position at which you released the button, and the mark will be left at the initial click position. See also the `mouse-track-adjust' command, on Sh-button1. ------------------------------ mouse-track-adjust: (event) Extend the existing selection. This should be bound to a mouse button. The selection will be enlarged or shrunk so that the point of the mouse click is one of its endpoints. This is only really meaningful after the `mouse-track' command (button1) has been executed. ------------------------------ mouse-track-and-copy-to-cutbuffer: (event) Makes a selection like `mouse-track', but also copies it to the cutbuffer. ------------------------------ mouse-track-delete-and-insert: (event) Make a selection with the mouse and insert it at point. This is exactly the same as the `mouse-track' command on button1, except that point is not moved; the selected text is immediately inserted after being selected; and the text of the selection is deleted. ------------------------------ mouse-track-insert: (event) Make a selection with the mouse and insert it at point. This is exactly the same as the `mouse-track' command on button1, except that point is not moved; the selected text is immediately inserted after being selected; and the selection is immediately disowned afterwards. ------------------------------ mouse-window-to-region: (event) Narrow window to region between cursor and mouse pointer. ------------------------------ next-command-event: (&optional event) Returns the next available "user" event from the window system or terminal driver. Pass this object to dispatch-event to handle it. If an event object is supplied, it is filled in and returned, otherwise a new event object will be created. The event returned will be a keyboard, mouse press, or mouse release event. If there are non-command events available (mouse motion, sub-process output, etc) then these will be executed (with `dispatch-event') and discarded. This function is provided as a convenience; it is equivalent to the lisp code (while (progn (next-event event) (not (or (key-press-event-p event) (button-press-event-p event) (button-release-event-p event) (menu-event-p event)))) (dispatch-event event)) ------------------------------ next-event: (&optional event prompt) Returns the next available event from the window system or terminal driver. Pass this object to dispatch-event to handle it. See also the function next-command-event, which is often more appropriate. If an event object is supplied, it is filled in and returned, otherwise a new event object will be created. ------------------------------ next-extent: (extent_obj) Find next extent after EXTENT. If EXTENT is a buffer return the first extent in the buffer. ------------------------------ next-screen: (&optional screen miniscreen visible-only-p) Return the next screen in the screen list after SCREEN. If MINISCREEN is non-nil, include the global-minibuffer-screen if it has its own screen. If VISIBLE-ONLY-P is non-nil, then cycle through the visible screens, instead of all screens. ------------------------------ other-window-any-screen: (n) Select the ARG'th different window on any screen. All windows on current screen are arranged in a cyclic order. This command selects the window ARG steps away in that order. A negative ARG moves in the opposite order. However, unlike `other-window', this command will select a window on the next (or previous) screen instead of wrapping around to the top (or bottom) of this screen, when there are no more windows. ------------------------------ pixel-name: (pixel) Returns the name used to allocate the given pixel. ------------------------------ pixelp: (obj) Whether the given object is a pixel. ------------------------------ pixmap-file-name: (pixmap) Returns the file name from which the given pixmap was read, or nil if the pixmap was created from Lisp data (the lisp data is not retained, since it usually won't be needed again might be quite large.) ------------------------------ pixmap-depth: (pixmap) Return the depth of the pixmap. This is 0 for a bitmap, or a positive integer for a pixmap. ------------------------------ pixmap-file-name: (pixmap) Returns the file name from which the given pixmap was read, or nil if the pixmap was created from Lisp data (the lisp data is not retained, since it usually won't be needed again might be quite large.) ------------------------------ pixmap-height: (pixmap) Return the height of the pixmap, in pixels. ------------------------------ pixmap-hotspot-x: (pixmap) Returns the X coordinate of the pixmap's hotspot. See `set-pixmap-hotspot'. ------------------------------ pixmap-hotspot-y: (pixmap) Returns the Y coordinate of the pixmap's hotspot. See `set-pixmap-hotspot'. ------------------------------ pixmap-width: (pixmap) Return the width of the pixmap, in pixels. ------------------------------ pixmapp: (obj) Whether the given object is a pixmap. ------------------------------ play-sound: (sound &optional volume) Play a sound of the provided type. See the variable sound-alist. ------------------------------ popup-dialog-box: (dbox_desc) Pop up a dialog box. A dialog box description is a list. The first element of a dialog box must be a string, which is the title or question. The rest of the elements are descriptions of the dialog box's buttons. Each of these is a vector, the syntax of which is essentially the same as that of popup menu items. They may have any of the following forms: [ "name" callback ] [ "name" callback "suffix" ] [ "name" callback : : ... ] The name is the string to display on the button; it is filtered through the resource database, so it is possible for resources to override what string is actually displayed. If the `callback' of a button is a symbol, then it must name a command. It will be invoked with `call-interactively'. If it is a list, then it is evaluated with `eval'. One (and only one) of the buttons may be `nil'. This marker means that all following buttons should be flushright instead of flushleft. Though the keyword/value syntax is supported for dialog boxes just as in popup menus, the only keyword which is both meaningful and fully implemented for dialog box buttons is `:active'. ------------------------------ popup-menu: (menu-description) Pop up the given menu. A menu description is a list of menu items, strings, and submenus. The first element of a menu must be a string, which is the name of the menu. This is the string that will be displayed in the parent menu, if any. For toplevel menus, it is ignored. This string is not displayed in the menu itself. If an element of a menu is a string, then that string will be presented in the menu as unselectable text. If an element of a menu is a string consisting solely of hyphens, then that item will be presented as a solid horizontal line. If an element of a menu is a list, it is treated as a submenu. The name of that submenu (the first element in the list) will be used as the name of the item representing this menu on the parent. Otherwise, the element must be a vector, which describes a menu item. A menu item can have any of the following forms: [ "name" callback ] [ "name" callback "suffix" ] [ "name" callback : : ... ] The name is the string to display on the menu; it is filtered through the resource database, so it is possible for resources to override what string is actually displayed. If the `callback' of a menu item is a symbol, then it must name a command. It will be invoked with `call-interactively'. If it is a list, then it is evaluated with `eval'. The possible keywords are this: :active
Same as in the first two forms: the expression is evaluated just before the menu is displayed, and the menu will be selectable only if the result is non-nil. :suffix "string" Same as "suffix" in the second form: the suffix is appended to the displayed name, providing a convenient way of adding the name of a command's ``argument'' to the menu, like ``Kill Buffer NAME''. :keys "string" Normally, the keyboard equivalents of commands in menus are displayed when the `callback' is a symbol. This can be used to specify keys for more complex menu items. It is passed through `substitute-command-keys' first. :style