1.1 Windows ¶

When you use the Lisp Machine, you can run many programs at once. You can have a Lisp listener, an editor, a mail reader, and a network connection program, or several of each, all running at the same time, and you can switch from one to the other conveniently. Interactive programs get input from the keyboard and the mouse, and send output to a screen. Since there is only one keyboard, it can only talk to one program at a time. However, each screen can be divided into regions, and one program can use one region while another uses another region. Furthermore, this division into regions can control which program the mouse talks to; if the mouse cursor position is in a region associated with a certain program, then mouse clicks are directed to that program, which is then allowed to decide what the clicks mean. Allocating access to screen space and input devices is the most important function of the window system.

The regions into which the screen is divided are known as windows. In your use of the Lisp Machine, you have encountered windows many times. Sometimes there is only one window visible on the screen; for example, when you cold-boot a Lisp Machine, it initially has only one window showing, and it is the size of the entire screen. If you start using the system menu’s Create, Edit Screen, or Split Screen options. you can make windows in various places of various sizes and flavors. Usually windows have a border around them (a thin black rectangle around the edges of the window), and they also frequently have a label in the lower-left hand corner or on top. This is to help the user see where all the windows are, what parts of the screen they are taking up, and what kind of windows they are.

The next several sections begin to explain the detailed concepts of how windows work and what their internal state is. You should probably read over these quickly the first time, without worrying about all the details. You really don’t have to understand all of the complexity to make simple use of the window system; it just helps if you know what sort of thing is going on.

1.2 Capabilities of Windows ¶

A window may or may not be exposed, which means that output can be done on it ((exposure)). At any time at most one window can be selected, which means that input can be done through it ((selection)). These two conditions constitute the window’s status.

Another kind of state information that every window has is its edges: its size and its position (see (sizes-and-positions)). You can specify these numerically, ask for the user to tell you (using the mouse), ask for a window to be near some point or some other window, and so on.

Windows can function as streams by accepting all the operations that streams accept. If you do input operations on windows, they read from the keyboard; if you do output operations on windows, they type out characters on the screen. The value of terminal-io (see (terminal-io-var)) is normally a window, and so input/output functions on the Lisp Machine do their I/O to windows by default.

A window whose flavor incorporates tv:stream-mixin supports all the standard input stream operations and may be passed as the input stream to functions such as read and readline (see (input)). Each such window has an input buffer holding characters that have been typed at the window but not read yet. You can force keyboard input into a window’s input buffer; frequently two processes communicate by one process’s forcing keyboard input into an input buffer from which another process is reading characters (see (tv:stream-mixin-force-kbd-input-method)).

Any window handles the standard output stream operations and can be passed as the output stream to functions such as print and format (see (output)). You can output characters at a cursor position, move the cursor around, selectively clear parts of the window, insert and delete lines and characters, and so on, by means of standard and not-so-standard stream operations. Output of text on windows provides additional features; for example, characters can be drawn in any of a large set of fonts (type faces), and you can switch from one to another within a single window (see (font-section)). Windows can define their own actions for exceptional conditions that affect output, such as reaching the right or bottom edge of the window, or printing more that a window-full without pausing (see (output-exceptions)).

In addition to characters from fonts, you can also display graphics (pictures) on windows (see (graphics-section)). There are operations to draw lines, circles, triangles, rectangles, arbitrary polygons, circle sectors, and cubic splines.

Each window can have any number of blinkers (see (blinkers)). Most windows have one blinker that follows the window’s cursor position; this blinker normally appears as a blinking rectangle. But blinkers need not follow the cursor and need not actually blink (some do and some don’t). For example, the editor shows you what character the mouse is pointing at; this blinker looks like a hollow rectangle. The arrow that follows the mouse is a blinker, too. Blinkers are used to add visible ornaments to a window, or temporary modifications to a window’s normal display. Blinkers are flavor instances with their own standard operations.

Windows are the standard interface to the mouse (see (mouse)). Both mouse motion and mouse clicks are normally handled by messages sent to the window over which the mouse is positioned.

A window’s area of the screen is divided into two parts. Around the edges of the window are the four margins; while the margins can have zero size, usually there is a margin on each edge of the window, holding a border and sometimes other things, such as a label. The rest of the window is called the inside; regular character output and graphics drawing all occur on the inside part of the window. The margins and inside of the window are managed separately so that mixins to add things to the margins can be independent of the program that draws in the window’s inside. See (margins).

For greater flexibility in subdividing a window into multiple areas of different uses, you can create inferior windows or panes within the window. The main window is then called a frame. Each pane can be of a different flavor suitable to its own purpose; thus Peek uses a frame which has a menu and a scrolling window as its two panes. See (window-hierarchy), for information on the hierarchy of windows, and (frames), for a description of frames.

The asynchronously intercepted characters (such as Control-Abort) which take effect instantaneously when typed are handled by the selected window. Each window can specify its own. See (asynchronous-intercepted-characters).

A window can have an associated process. For example, when you type Control-Abort, the process aborted is the one associated with the selected window. Exactly how processes and windows relate depends on the flavor of the window, and, as usual, there are several operations to manipulate the connections. See (processes).

Notifications are a facility for displaying messages from events taking place asynchronously and not related to the program you are running (errors in background processes, qsends from other users, file servers planning to go down, etc.). Notifications work through operations on the selected window, so each window can decide how to display a notification. See (notifications).

Screens are represented by flavor objects also; these are not windows, but share some of the operations and instance variables of windows (see (screens)). Windows and screens collectively are called sheets. Each screen object usually corresponds to a particular piece of display hardware. Screens can be either black-and-white or color. Color screens have more than one bit for each pixel, and most operations on windows do something reasonable on color screens. But the extra bits give you extra flexibility, and so there are some more powerful things you can do to manipulate colors. Color screens also have a color map which specifies which values of the pixels display which colors. See (color).

The who line at the bottom of the screen shows the user something about the state of the Lisp Machine. The window system software implements the who line as a separate screen even though it appears on the same TV monitor as the main screen and its windows. This is why you cannot move the mouse into the who line area, or make windows on the main screen hide the who line. See (who-line) for more information on the who line and how it is interfaced and implemented.

1.3 Higher Level Window Facilities ¶

The higher level window facilities are window flavors that combine the basic capabilities of windows appropriately to provide directly usable techniques for particular common applications. These facilities include menus and other choice windows, typeout windows, and scrolling windows.

Menus allow the user to choose one or several of a fixed set of items. The system menu that you get from double-click-right is an example of one. See (menu). Multiple choice windows allow the user to specify an answer to each of a set of similar multiple-choice questions (see (multiple-choice)). The editor command Meta-X Kill or Save Buffers shows an example of one.

Choose-variable-values windows allow the user to view and modify the values of a set of variables, each variable printed and read according to its own range of possible values. One variable might allow only numbers, while another variable’s value might be restricted to a list of pathnames. See (choose-variable-values).

Typeout windows allow windows such as scroll windows and editor windows, which normally present displays reflecting permanent data bases, to print output in response to individual commands. The typeout window is an inferior of the other window, and exposes itself when output is done on it.

Scrolling windows allow the programmer to define a display which the user can then scroll through. The scrolling window facility provides for scrolling, redisplay, and interaction with the mouse, requiring the programmer only to specify the entire contents to be scrolled through. There are two types of scrolling windows, text scroll windows ((text-scroll-windows)) and general scroll windows ((scroll-windows)), the former being less powerful but simpler. Note that there is a standard interface protocol for the mouse to request scrolling (see (scroll-protocol)). You need not use one of the standard scrolling window facilities to make a window that can scroll if you are willing to implement the scrolling yourself. For example, editor windows and menus can also scroll.

1.4 Windows as Flavor Instances ¶

In the Lisp world, each window is a flavor instance, an instance of some flavor of window. There are many different window flavors available; some of them are described in this manual. All of them contain the component tv:minimum-window.

.defflavor tv:minimum-window The flavor on which all window flavors are built. Any window flavors you define should include this component. This flavor itself is made of the components tv:essential-window, tv:essential-activate, tv:essential-expose, tv:essential-set-edges and tv:essential-mouse. tv:minimum-window has no methods of its own; all are inherited from those components. So you will at times (in the debugger) run across methods of those component flavors. You will also run across methods of tv:sheet, a component of tv:essential-window. However, there is no need for you as a programmer to pay attention to the distinctions among these flavors, and in this manual all the operations, instance variables and init options of tv:minimum-window are documented as being "of windows" rather than of any specific flavor. .end_defflavor

.defflavor tv:window This flavor of window has several mixins that provide much generally useful functionality, including the ability to select the window, graphics operations, labels and borders.

(defflavor tv:window () 
   (tv:stream-mixin tv:borders-mixin tv:label-mixin 
    tv:select-mixin tv:delay-notification-mixin 
    tv:graphics-mixin tv:minimum-window))

The operations of these mixins are specifically identified in this manual. Use the mixins, or use the flavor tv:window, if you want the operations to be available. .end_defflavor

It is often necessary to mix flavors to get the desired window behavior. When doing this, you must pay attention to the correct ordering of flavor components. The earlier components will override later ones. For example, if you want to make a window that will print out notifications on itself by mixing in tv:notification-mixin, you must put it in front of tv:window:

(defflavor my-window () (tv:notification-mixin tv:window))

If you put them in the other order, as in

(defflavor my-window () (tv:window tv:notification-mixin))

you get something equivalent to tv:window. The tv:notification-mixin’s effect is completely lost. The whole point of tv:notification-mixin is that it should override some methods of tv:window (inherited from tv:delay-notification-mixin), and in fact it defines the same operations in a different way. It follows that if tv:notification-mixin comes last, it will be overridden instead.

It is almost always correct to put mixins first in the ordering so that they will override whatever they are added to. One exception occurs with flavors of margin item; there, the ordering is used to control the spatial position of the margin items.

Screens are also represented by flavor instances, which share some of the characteristics of windows because they share the component flavor tv:sheet. Screens are described fully in (screens).

.defflavor tv:sheet tv:sheet is a flavor that windows and screens share. It is also what provides the structure required by the microcode display primitives. Operations defined by this flavor are documented as being "of windows and screens" in this manual. .end_defflavor

Much of the contents of this manual is devoted to describing the instance variables and operations of various flavors of window. They are grouped below by functionality.

There is a vague convention sometimes followed for naming flavors of windows. Here the word frobboz is used to stand for any feature, attribute, or class of windows that would appear in a flavor name (e.g. peek, lisp-listener, or delayed-redisplay-label). Naming conventions are different for instantiable flavors (which are complete and can support instances of themselves) and mixin flavors (which are incomplete and only supply one particular aspect of behavior).

• frobboz An instantiable flavor whose most distinguishing characteristic is that it is a frobboz. frobboz is preferred to frobboz-window except when it is necessary to make a distinction.
• frobboz-mixin A flavor which provides the frobboz feature when mixed into other flavors, but is not instantiable. Such mixins often have no components, just :required-flavors.
• basic-frobboz This form of name is used instead of frobboz-mixin when the flavor is regarded as altering the "essential character" of the window. It does not work to mix two "basic" flavors together unless they are designed to work together. In certain cases a basic-frobboz may contain tv:minimum-window as a component, and may even be instantiable, but usually it is a mixin that must be mixed with tv:minimum-window and other things in order to work.
• essential-frobboz
• essential-frobboz-mixin A name like this is generally used for a component of frobboz-mixin, containing the heart of the frobboz facility but not its bells and whistles or its specific interface.

1.5 Using a Window ¶

Many programs never need to create any new windows. Often it suffices to use the standard input, output and graphics operations on an existing window, such as a Lisp listener which is the value of terminal-io when your program is called. For example, here is a graphics demo that will draw a pattern of xored circles on any window which has tv:graphics-mixin (such as a Lisp listener).

(defun green-hornet (&optional (window terminal-io)
		     (separation 40))
 (hacks:with-real-time
  (send window ':clear-screen)
  (send window ':home-down)
  (multiple-value-bind (iw ih)
      (send window ':inside-size)
    (let ((center-x1 (- (truncate iw 2)
			(truncate separation 2)))
	  (center-x2 (+ (truncate iw 2)
			(truncate separation 2)))
	  (center-y (truncate ih 2)))
      (do ((i (- (min center-y center-x1) 10.)
	      (1- i)))
	  ((<= i 5))
	(send window ':draw-circle
	      (if (bit-test 20 i) center-x1 center-x2)
	      center-y
	      i))))
  (send window ':tyi)
  t))

Such programs should try to stick to the most widely-implemented operations. The ideal is to use only the standard stream operations documented in (stream-protocol); then your program will run even with streams that are not windows. With graphics programs such as green-hornet you are forced to use some windows-only operations, but it is still best to stick to the operations provided by the flavor tv:window.

1.6 Creation of Windows ¶

When you want to create a flashy and sophisticated user interface, especially involving mouse-sensitivity or automatic updating, it is time to consider creating your own windows (and your own window flavors, perhaps).

To create a window, use the functions make-instance or instantiate-flavor. (Old programs usually use tv:make-window, which is now equivalent to make-instance but was different in the past).

Function: make-instance flavor-name &rest init-options ¶

Creates, initializes, and returns a new instance of the specified flavor. The init-options argument contains alternating keywords and values; the keywords must be init options accepted by the flavor you are using. The init options accepted by various window flavors are described in this manual.

Example:

(make-instance 'tv:lisp-listener
	       ':borders 4
	       ':font-map (list fonts:bigfnt)
	       ':vsp 6
	       ':edges-from ':mouse
	       ':expose-p t)

creates an exposed Lisp listener with big characters and lots of vertical space between lines.

For more information on this function and on instantiate-flavor, see (manual-make-instance-fun).

Variable: tv:sheet-area ¶

The area in which windows are by default created.

.defmetainitoption windows :name name Every window has a name, which is used primarily for printing the window as a Lisp object, but also serves as a default for the window’s label. If you do not specify a name, the default is constructed from the flavor name and a counter (each flavor has its own) to make the name unique. .end_defmetainitoption

.defmetainstvar windows tv:name The name of the window. .end_defmetainstvar

2.1 Hierarchy of Windows ¶

Several Lisp Machine system programs and application programs present the user with a window that is split up into several sections, which are usually called "window panes" or "panes". For example, the inspector has six panes in its default configuration: the one you type forms into at the top, the menu, the history list, and the three inspection panes below the first three. The window debugger and ZMail also use elaborate windows with panes. Just as windows on a screen can subdivide the screen, a window’s panes subdivide the screen space of the window. With programs such as the editor, inspector and ZMail, it may not be obvious that the windows you see are panes in another window because that window occupies the full screen. If you go into Edit Screen and reshape one of these, you will see clearly how there is a window with subwindows.

In fact, the panes in an inspector are related to the inspector’s main window just as that window is related to the screen. Windows are arranged in a hierarchy, each window having a superior and a list of inferiors. Usually the top of the hierarchy is a screen. In the example above, the inspector window is an inferior of the screen, and the panes of the window are inferiors of the inspector window. The screen itself has no superior (if you were to ask for its superior, you would get nil).

A window’s superior, its superior’s superior, and so on, are collectively called its ancestors. A window’s inferiors and their inferiors, and so on, are called its descendants.

The position of a window is remembered in terms of its relative position with respect to its superior. To figure out where a window is on the screen, we add this relative position to the absolute position of the superior (which is computed the same way, recursively; the recursion terminates when we finally get to a screen). The important thing about this is that when a superior window is moved, all its inferiors are moved the same amount; they keep their relative position within the superior the same. You can see this if you play with the Move Window command in Edit Screen.

Normally Edit Screen edits the arrangement of the windows on a screen, but it can also edit the arrangement of inferiors (panes) of a window in the same fashion. If you click right on Edit Screen, you get a menu containing all the superiors of the window you pointed at, up to the screen. You can then edit the inferiors of whichever one you choose.

So, what Edit Screen really does is to manipulate a set of inferiors of some specific superior, which may or may not be a screen. The set of inferiors that you are manipulating is called the active inferiors set; each inferior in this set is said to be active. The active inferiors are all fighting it out for a chance to be visible on their superior. If no two active inferiors overlap, there is no problem; they can all be visible. However, whenever two overlap, only one of them can be on top. Edit Screen lets you change which active inferiors get to be on top. There is also a part of the window system called the screen manager whose basic job is to keep this competition straight. For example, it notices that a window that used to be covering up part of a second window has been reshaped, and so the second window is no longer covered and can be made visible. Inactive windows are never visible until they become active; when a window is inactive, it is out of the picture altogether. The screen manager will be discussed at length later ((screen-manager)).

Each superior keeps track of all of its active inferiors as a list in the instance variable tv:inferiors, and each inferior window keeps track of its superior, in the instance variable tv:superior. Superior windows do not keep track of their inactive inferiors; this is a purposeful design decision, in order to allow unused windows to be reclaimed by the garbage collector. So, when a window is deactivated, the window system doesn’t touch it until it is activated again.

.defmetamethod windows :activate Makes the window active in its superior. .end_defmetamethod

.defmetamethod windows :deactivate Makes the window cease to be active in its superior. .end_defmetamethod

.defmetainitoption windows :activate-p t-or-nil If this option is specified non-nil, the window is activated after it is created. The default is to leave it deactivated. .end_defmetainitoption

.defmetamethod windows :kill Killing a window deactivates it but also makes a positive effort to get rid of other entities such as processes or net connections that may be associated with the window. If a window has these things, it may not be satisfactory to just allow the window to be garbage collected; therefore, the :kill operation is provided. A command for the user to get rid of windows should use :kill rather than :deactivate. .end_defmetamethod

.defmetamethod "windows and screens" :active-p t if this window is active in its superior. A screen is always considered active. .end_defmetamethod

.defmetamethod "windows and screens" :inferiors Returns this window or screen’s list of inferiors. .end_defmetamethod

.defmetamethod "windows and screens" :superior Returns this window or screen’s superior. For a screen, it is nil. .end_defmetamethod

.defmetamethod windows :set-superior new-superior Makes this window an inferior of new-superior. .end_defmetamethod

.defmetainitoption windows :superior superior Makes the new window an inferior of superior. If this is not specified, the default is tv:mouse-sheet, which is initially the main black-and-white screen. .end_defmetainitoption

.defmetainstvar "windows and screens" tv:inferiors A list of the active inferiors. .end_defmetainstvar

.defmetainstvar "windows and screens" tv:superior In a window, the value is the window’s superior. In a screen, the value is nil. .end_defmetainstvar

Function: tv:sheet-superior window-or-screen ¶

Function: tv:sheet-inferiors window-or-screen ¶

Accessor defsubsts for the corresponding instance variables.

Function: tv:sheet-me-or-my-kid-p sheet me ¶

t if sheet is an indirect inferior, zero or more levels down, of the sheet me.

Function: tv:map-over-exposed-sheets function ¶

Calls function on every exposed sheet, starting with the screens, their inferiors, and so on down.

Function: tv:map-over-exposed-sheet function sheet ¶

Calls function on every exposed inferior of sheet, to all levels, including sheet itself.

Function: tv:map-over-sheets function ¶

Calls function on every active sheet, starting with the screens, their inferiors, and so on down.

Function: tv:map-over-sheet function sheet ¶

Calls function on every active inferior of sheet, to all levels, including sheet itself.

2.2 Screens ¶

The topmost nodes of the window hierarchy are actually screens rather than windows, a screen being an instance of the flavor tv:screen.

.defflavor tv:screen Screens are also flavor instances, whose flavors incorporate tv:screen. Screens are not windows, but they have much in common with windows, because both incorporate the flavor tv:sheet ((tv:sheet-flavor)). .end_defflavor

Usually each screen object represents an individual piece of display hardware. However, the main black-and-white physical screen that all Lisp Machines have is logically divided into two screens, with different screen objects. These are tv:main-screen and tv:who-line-screen. Because these are separate screens, windows on the main screen cannot be extended onto the who line, and the mouse cannot move onto the who line, etc.

Screens are the objects that know how to parse font specifiers (user-level names for fonts) into font objects that can be used for display. See (font-specifier). Also, each screen can specify a font for each of the standard font purposes (:default, :label, :menu, etc.). See (font-purposes).

Function: tv:sheet-get-screen sheet ¶

Returns the screen that sheet is an indirect inferior of (sheet itself, if it is a screen).

Variable: tv:main-screen ¶

The screen object that represents the Lisp Machine black-and-white display, except for the who line area. This is default superior for windows created with tv:make-window.

Variable: tv:who-line-screen ¶

The screen object that represents the who line area. Each field of the who line is a separate window on this screen.

Variable: tv:default-screen ¶

This is the screen that is "normally used". It is initialized to be the main screen. Certain functions that create a window without reference to the mouse use it as a default for the superior of the window, and window resources with a superior as parameter often create one window initially, with the default screen as the superior.

Variable: color:color-screen ¶

This is the color screen for the 4-bit-pixel color display that some Lisp Machines have. The screen object is always present, but is exposed only when the machine actually has a color screen. See (color).

Variable: tv:all-the-screens ¶

A list of all screen objects. With this list, you can begin a tree walk to cover all active windows.

Function: tv:set-tv-speed &optional (speed 60.5) (wasted-lines 0) ¶

Sets the scanning rate of the main screen, in vertical sweeps per second, to speed. speed is usually a flonum.

The vertical size of the screen is inversely proportional to the number of vertical scans per second, because the display rate in horizontal scan lines per second is fixed.

A nonzero value of wasted-lines directs the system to refrain from using that many horizontal scan lines at the bottom of the screen. If you are using MIT software on a machine built by Symbolics, you may need to do this, since the screens are typically misaligned so that the who line is obscured by the screen’s cabinet. A value of 20 to 30 generally does the trick.

2.3 Pixels ¶

A screen displays an array of pixels. Each pixel is a little dot of some brightness and color; a screen displays a big array of these dots to form a picture. Everything you see on the screen, including borders, graphics, characters, and blinkers, is made up out of pixels.

Each physical screen has a display memory which stores the values of all the pixels. On regular black-and-white screens, each pixel has one of only two values, lit up or not lit up, so the pixel is represented in memory by one bit. Usually 0 is used for the background of a window and the characters or lines on it are made of 1’s, so 1 can be considered "on" and 0 "off". On color screens, pixels have more than one bit. The usual sort of color screen has four bits per pixel. 0 is still often used as the background value and assigned the color black. There is no convention for the use of other pixel values.

Black and white screens have a hardware flag that controls the visual appearance of 1 and 0 pixels. In "black-on-white" mode, 1 is dark and 0 is bright, so windows appear with dark text on a white background. This mode is the default. In "white-on-black" mode, 1 is bright and 0 is dark. Users can switch between these modes with Terminal C.

An individual window can specify 1 for background and 0 for text; this is independent of white-on-black mode (which applies to the whole screen) and is requested with the :reverse-video-p init option or the :set-reverse-video-p operation (see (windows-set-reverse-video-p-method)). These work by controlling the alu functions used for drawing and erasing characters; see (alu-functions). Programs which use the window’s recommended alu functions for their drawing and erasing will automatically display in reverse-video when this is specified. The who line mouse documentation window is an example of a window which uses reverse-video.

Function: tv:black-on-white &optional (screen tv:default-screen) ¶

Make screen display one-bits as black, with zero-bits as white. (This is the default mode.)

Note that this works by setting a bit in the display hardware; as a result, if done on the main screen, it applies to the who line as well.

Function: tv:white-on-black &optional (screen tv:default-screen) ¶

Make screen display one-bits as white, with zero-bits as black.

Function: tv:complement-bow-mode &optional (screen tv:default-screen) ¶

Toggle whether screen displays one-bits as white or as black. This is what Terminal C does.

.definstvar tv:screen tv:bits-per-pixel 1 for a black-and-white screen, larger numbers for other kinds (4 for the standard color screen). .end_definstvar

.definstvar tv:screen tv:buffer The address of the screen memory, as a fixnum. .end_definstvar

.definstvar tv:screen tv:buffer-halfword-array An art-16b array containing the screen memory. .end_definstvar

.definstvar tv:screen tv:control-address The address of the screen’s control register which contains, among other things, the flag controlling black-on-white mode. .end_definstvar

2.4 Bit-Save Arrays ¶

The pixel values that make up a window’s screen image are called its contents. When a window is fully visible, its contents are displayed on a screen so that they can be seen. When the window is not fully visible, its contents are lost unless there is a place to save them. Such a place is called a bit-save array.

A bit-save array is an array of bits of sufficient size to hold a copy of the window’s contents. If a window has a bit save array, its contents are copied into the array when the window ceases to be fully visible. If the window becomes fully visible again, the contents are copied from the bit-save array back onto the screen. In the mean time, programs can use tv:sheet-force-access to do output into the bit-save array while the window is not visible (see (tv:sheet-force-access-fun)), and the window’s inferiors, if any, can be exposed and do output (see (exposure)).

When a window with a bit-save array is partially visible, the visible parts can be displayed correctly by copying them from the bit-save array. This is the behavior you observe if you make a small Lisp listener window with Create and have a full-screen window such as the initial Lisp listener or a Zmacs frame partially visible around it. It happens because the Lisp listener or Zmacs frame has a bit-save array.

If a window does not have a bit-save array, then there is no place to put its contents when it is not visible, so they are lost. When the window becomes visible again, it will try to redraw its contents; that is, to regenerate the contents from some state information in the window. This is done by the :refresh operation documented below. Some windows can do this; for example, editor windows can regenerate their contents based on the editor buffers they are displaying. Other windows, such as Lisp listeners, do not remember what was displayed on them and cannot regenerate their previous contents. Such windows just leave their contents blank, except for the margins (see (margins)), which all windows can regenerate.

The advantage of having a bit-save array is that losing and regaining visibility does not require the contents to be regenerated; this is desirable since regeneration may be computationally expensive, or even impossible. The disadvantage is that the bit-save array can be large and swapping it in can be slow.

When a frame is in use, giving the frame a bit-save array enables the contents of the frame and all the panes to be preserved if the frame ceases to be fully visible. Bit-save arrays for the panes would come into play only if panes were shuffled or substituted within the frame; in most applications, this happens never or rarely, and is accompanied by a thorough redisplay. So normally the frame gets a bit-save array and the panes do not.

.defmetainstvar windows tv:bit-array This instance variable of all windows holds the window’s bit array, or nil if it has none. .end_defmetainstvar

Function: tv:sheet-bit-array window ¶

Accessor defsubst for the corresponding instance variable.

.defmetamethod windows :bit-array Returns the window’s bit array, or nil if it has none. .end_defmetamethod

.defmetamethod windows :save-bits Returns non-nil if this window saves its bits when not exposed. .end_defmetamethod

.defmetamethod windows :set-save-bits flag Tells this window to start or stop saving its bits when not exposed. flag is t to start or nil to stop. .end_defmetamethod

.defmetainitoption windows :save-bits flag flag may be t, nil or :delayed. :delayed causes the window to acquire a bit-save array the first time it is deexposed, but not before. .end_defmetainitoption

.defmetamethod windows :refresh &optional (type ':complete-redisplay) Restore the saved contents of the window or regenerate the contents, according to the value of type (and to whether the window has a bit-save array).

Here are the possible values of type:

• :complete-redisplay This is the default. The window’s present bit image is completely discarded and regenerated from scratch. The margins are redrawn by invoking :refresh-margins. The default definition of :refresh just leaves the inside blank except for refreshing any exposed inferiors.

  If the window has no bit-save array, type is ignored and the actions for :complete-redisplay are always used.

• :use-old-bits The complete contents are restored from the bit-save array. This is specified by the system when a window is exposed.
• :size-changed This keyword is specified when the window’s size has been changed. The contents are restored from the bit-save array, and then the margins are refreshed with :refresh-margins.
• :margins-only This keyword is specified when the inside portion of the window is completely undisturbed, and only the margins need to be refreshed. The system treats it just like :size-changed.

Window flavors ought when possible to provide :after daemons for :refresh, to complete the job of redrawing the window, which the system itself cannot know how to do. When these daemons run, the instance variable tv:restored-bits-p will be non-nil if the window contents were restored from a bit-save array. If this is so, there is no need for the :after daemons to do anything, except perhaps if the window’s inside size has changed. .end_defmetamethod

.defmetainstvar windows tv:restored-bits-p In :after daemons of :refresh (and therefore also of :expose), this is t if the contents were restored from a bit-save array. If it is nil, the inside of the window was left blank and must be regenerated to whatever extent that is possible. .end_defmetainstvar

2.5 Screen Arrays and Exposure ¶

This section discusses the concepts of screen arrays and of exposed windows. These have to do with how the system decides where to put a window’s contents (its pixels), how the notion of visibility on the screen is extended into a hierarchy of windows, and how programs can control which windows are visible. Do not feel it is your fault if this seems complicated; you do not need to understand it fully on your first reading of the manual.

Each window or screen can have a screen-array, which is where output drawn on the window should go. Drawing characters or graphics is done by changing elements of the window’s screen array. The screen array is stored in the instance variable tv:screen-array. The variable can also be nil, to say that the window does not have a screen array at the present time.

A screen normally has a screen array that is displaced to the special memory that the screen’s hardware displays from. A window that is visible has a screen array; it is an indirect array that points into the area of the superior’s screen-array where the inferior gets displayed on the superior. For example, consider a visible window whose superior is a screen and whose upper-left-hand corner is at location (100,100) in the screen. The window’s screen-array would be an indirect array whose (0,0) element is the same as the (100,100) element of the screen. If you were to set a pixel in the window’s screen-array, the corresponding pixel in the screen (found by adding 100 to each coordinate) would be set to that value.

A visible window more than one level down from the screen has a screen array that indirects more than once. The window’s screen-array points into the middle of its superior’s screen array, which points into the middle of the superior’s superior’s screen array, and so on until the screen is reached. When typeout is done on the window, it will appear on the screen, offset by the combined offsets of all the ancestors, so that it will appear in the correct absolute position on the screen.

Sometimes a window is unable to have a screen array that points to its superior’s screen array. For now, let’s not ask why this might happen, but consider instead what to do about the screen array when this does happen. There are two alternatives. If the window has a bit-save array, then the bit-save array is used as the screen array. If there is no bit-save array, there can be no screen array either. The window’s tv:screen-array variable becomes nil, and there is nowhere for output on this window to go.

For a window w with a bit-save array, w’s inferiors are not affected by where w’s screen array points. w always has a screen array, and its inferiors’ screen arrays can point to that.

But if w has no bit-save array, it may have nil instead of a screen array, and in that case it is impossible for w’s inferiors to have screen arrays pointing into w’s screen array. So they in turn must use their bit-save arrays, if any, as screen arrays, or not have screen arrays. The effect propagates down the hierarchy.

So we see one possible reason why a window may be unable to have a screen array that points into its superior’s: if the superior doesn’t have a screen array at all. There is one other reason: the superior may deny permission for this window to point its screen array into the superior. The superior has an instance variable tv:exposed-inferiors which record all the inferiors permitted to do this. (Only active inferiors are allowed.) This permission can be granted or revoked at any time, and is called exposability. Each window can be made exposable or not exposable using the :expose and :deexpose operations. So, if a window’s superior does not have a screen array, or if the window is not exposable, then the window must scrounge up a screen array itself if it can.

A window is said to be exposed if it has a screen array that points into its superior’s screen array. Note that a window must be exposable in order to be exposed, but the converse is not true. An exposable window is exposed as well if and only if its superior has a screen array.

An exposed window is not necessarily visible. A window is visible if its screen array points, through some number of levels of indirection, into the middle of the screen’s screen array. An exposed window’s screen array points into the middle of something, but that may be a bit-save array in a deexposed ancestor some number of levels up. A window that is exposed but not visible must have some ancestors that are not exposed, and at least one of them must not be exposable either. This diagram of a window w8 and its ancestors shows the pattern of exposed and deexposed windows and how it comes about.

s <-- w1 <-- w2 <-- w3 <-- w4 <-- w5 <-- w6 <-- w7 <-- w8
exposable    not!   exposable again...
				  w5 has a bit-save array
exposed...   deexposed...                exposed...
visible...   invisible...	      ...still invisible...

Output is allowed on a window whenever the window is exposed. Usually exposed windows are visible and the output can be seen on the screen. But output to an exposed window with a deexposed ancestor is also permitted. Then the output goes into the middle of that ancestor’s bit-save array rather than onto the screen. Such output cannot actually be seen. But if the unexposable ancestor that must exist is made exposable, the bit-save array will be copied onto the screen and the output already done will be seen.

Output is not normally allowed on a deexposed window, even if the window has a screen array which is its bit-save array. However, in this case, you can use tv:sheet-force-access to override the prohibition and output onto the bit-save array. Use of :permit as the window’s deexposed typeout action (see (deexposed-typeout-action)) allows all output on such windows to proceed and draw in the bit-save array. A deexposed window with no bit-save array cannot have output done on it in any fashion since it has no contents.

The :expose operation makes a window exposable. If at that time its superior has a screen array, the window will become exposed as well. Or, if the superior later acquires a screen array, the window will become exposed then. This can happen if the superior itself is exposed, or if the superior is given a bit-save array with the :set-save-bits operation.

The :deexpose operation always makes the window unexposable and therefore not exposed.

It is possible for a screen to be deexposed. In particular, if a Lisp Machine does not have a color display physically attached to it, there is still a "color screen" Lisp object in the Lisp world, but it is deexposed (and so are any immediate inferiors it may have). This is so saved Lisp environments can be moved easily between machines with different hardware configurations. The screen object is left deexposed so that programs will not try to output to it. The screen is exposed whenever the Lisp Machine system is booted on a machine that actually has a color screen; then all its exposable inferiors become exposed too. For screens, there is no distinction between exposed and exposable, since there is no superior to have a say in the matter.

In order to maintain the model that windows are like pieces of paper on a desk, it is important that no two windows that both occupy some piece of screen space be exposed at the same time. To make sure that this is true, whenever a window becomes exposed, the system deexposes any of its exposed siblings that it overlaps. (Note: this is not true for temporary windows; see (temporary-window).)

.defmetamethod "windows and screens" :expose &optional inhibit-blinkers bits-action new-left new-top Makes the window exposable, and exposed if possible. This is a very useful operation to attach daemons to, but remember that this operation may be performed on a window that is already exposable. The daemons must not make the assumption that the window is just becoming exposable. If the window is not a direct inferior of the screen, it may not be becoming exposed either.

If the window is not active in its superior, it is first activated.

The arguments to the :expose operation are supplied by the system and usually of interest only to the system’s methods. User invocations of this operation should usually supply no arguments.

If the window actually becomes visible, the window’s blinkers normally appear with their deselected visibilities. If inhibit-blinkers is non-nil, the blinkers are not acted on. If the window is being exposed in order to select it, this is used to save time.

If the window actually becomes visible, bits-action controls how it is put back on the screen. It can be :noop, :restore or :clean. If it is :noop, the window’s screen area is not touched. This is used only in very unusual cases. If it is :clean, the window is sent a :refresh message with argument :complete-redisplay, which should make the window redraw itself from scratch if it can. If bits-action is :restore, the window is sent a :refresh message with argument :use-old-bits, which should make the window copy its bit-save array onto the screen. nil as the bits-action is equivalent to :restore for windows with bit-save arrays and to :clean for windows without them.

new-left and new-top are the offsets within the superior at which to expose the window. They default to the window’s current offsets. These arguments are for use by the :set-edges operation; you should not pass them.

A window cannot be made exposable unless its full size fits within the superior. .end_defmetamethod

.defmetamethod "windows and screens" :deeexpose &optional save-bits-p screen-bits-action remove-from-superior Makes the window not exposed and not exposable. This is a useful operation to add daemons to.

The arguments to the :deexpose operation are supplied by the system, and are usually of interest only to the system’s methods.

save-bits-p defaults to :default. It can also be :force or nil. :default means the bits are saved if the window has a bit-save array. :force gives the window a bit-save array if it doesn’t already have one, so that the bits are always saved. nil does not save the bits.

screen-bits-action controls what to do to the bits on the screen. It may be :noop to do nothing to them, or :clean to erase the area occupied by the window.

If remove-from-superior is nil, the window remains exposable. You should always use t (which is the default) for this argument. The window system uses nil as part of implementing deexposure of an exposable window whose superior loses its screen array. Use of nil at any other time would lead to incorrect results. .end_defmetamethod

.defmetainitoption windows :expose-p t-or-nil If this option is specified non-nil, the window is made exposable after it is created. The default is to leave it deexposed. If the value of the option is not t, it is used as the first argument to the :expose operation (the inhibit-blinkers argument). .end_defmetainitoption

.defmetamethod "windows and screens" :exposable-p t if the window is exposable. .end_defmetamethod

.defmetamethod "windows and screens" :exposed-p t if the window is exposed. .end_defmetamethod

.defmetamethod "windows and screens" :exposed-inferiors Returns a list of all exposable inferiors of this window or screen. .end_defmetamethod

Special Form: tv:with-sheet-deexposed (sheet) &body body ¶

Executes the body with sheet deexposed. If sheet had been exposed, it is reexposed when body exits. Operations that change things about the window often make use of this to reduce the complicated case of an exposed window to the simpler case of a deexposed one.

.defmetamethod "windows and screens" :screen-array Returns the window or screen’s screen array, or nil. .end_defmetamethod

.defmetainstvar "windows and screens" tv:exposed-p t if the window is exposed. .end_defmetainstvar

.defmetainstvar "windows and screens" tv:exposed-inferiors A list of all exposable inferiors of this window or screen. .end_defmetainstvar

.defmetainstvar "windows and screens" tv:screen-array The screen array, or nil if there is none. .end_defmetainstvar

Function: tv:sheet-exposed-p window-or-screen ¶

Function: tv:sheet-exposed-inferiors window-or-screen ¶

Function: tv:sheet-screen-array window-or-screen ¶

Accessor defsubsts for the corresponding instance variables.

2.6 Ability to Output ¶

Whether a window is exposed usually controls whether output can be done on it. In a deexposed window a flag called the output hold flag is normally 1. This causes an output hold exception if an attempt is made to output to the window. The normal result of an output hold exception is that the process doing output waits until the output hold flag is clear. The process wait state during this wait is "Output Hold".

The output hold flag is also set in a window that has exposed inferiors, because output on the window would overwrite the inferiors.

Function: tv:sheet-output-hold-flag window ¶

1 to indicate an output hold exception, or 0 to permit output on the window. This is setf’able.

When a process attempts to type out on a window which is deexposed and has its output hold flag set, what happens depends on the window’s deexposed typeout action. The deexposed typeout action can be any of certain keyword symbols, or it can be a list. After the specified action is taken, if the output hold flag is still set, the process will wait for it to clear. The interesting thing is that the action may affect the value of the output hold flag.

.defmetainstvar windows tv:deexposed-typeout-action The window’s deexposed typeout action. .end_defmetainstvar

.defmetamethod windows :deexposed-typeout-action .defmetamethod1 windows :set-deexposed-typeout-action action Get or set the window’s deexposed typeout action. .end_defmetamethod

.defmetainitoption windows :deexposed-typeout-action action Initializes a window’s deexposed typeout action to action. .end_defmetainitoption

Function: tv:sheet-deexposed-typeout-action window ¶

Accessor defsubst for the instance variable.

Here are the possible values of deexposed typeout action:

• :normal "deexposed typeout action" This, the default, means "no action". Therefore, the process will always have to wait for the output hold flag to clear.
• :expose "deexposed typeout action" The action is to send the window an :expose message. This may expose the window (if the superior has a screen-array), and if it does expose the window then the output hold flag will probably be cleared, allowing typeout to proceed immediately. If the superior is the screen, the :expose option provides a very different user interface from the :normal option.
• :permit "deexposed typeout action" This means to permit typeout even though the window is not exposed, as long as the window has a screen array; i.e., it may type out on its own bit-save array even though it is not exposed. The next time the window is exposed, the updated contents will be retrieved from the bit-save array.

  The action for :permit is to turn off the output hold flag if the window has a screen array. This mode has the disadvantage that output can appear on the window without anything being visible to the user, who might never see what is going on and might miss something interesting.

  It is possible to request that output in this mode to partially visible windows be transferred to the screen periodically. See (deexposed-permit-in-background).

• :notify "deexposed typeout action" This means that the user should be notified when there is an attempt to do output on the window. The action taken is to send the :notice message to the window with the argument :output (see (windows-notice-method)). The default response to this is to notify the user that the window wants to type out and to put the window on a list for Terminal 0 S to select it. Supdup and Telnet windows have :notify deexposed typeout action by default.
• :error "deexposed typeout action" The action is to signal an error.
• a list, (operation arguments...) The action is to send the window a message with operation and arguments.

Functions such as ed, whose purpose is to select a window for the user, should not return immediately. If ed returned immediately, then when called in a Lisp listener with its deexposed typeout action set to :expose, the printing of the value returned by ed would immediately switch back to the Lisp listener, which defeats the purpose of ed. To avoid this behavior, ed calls tv:await-window-exposure.

Function: tv:await-window-exposure ¶

Wait until terminal-io is exposed (more precisely, until its :await-exposure operation returns).

.defmetamethod windows :await-exposure Does not return until the window is exposed. (Some window flavors implement it differently). .end_defmetamethod

Special Form: tv:sheet-force-access (window) body ¶

tv:sheet-force-access allows you to do typeout on a window that has a screen array even if its output hold flag is set. It works by turning off the output hold flag temporarily around the execution of the body. This is useful for drawing on a window while it is not visible. For example, changing the menu items of a menu redraws the menu contents immediately even if the menu is not visible; this is because when the menu does become visible it looks better to the user for it to become visible in one instant with the correct contents.

If the window is exposed, tv:sheet-force-access goes ahead and outputs to it. If the window is not exposed but has a bit-save array, the output goes there.

If the window is not exposed and has not bit-save array tv:sheet-force-access doesn’t do anything at all; it just returns without evaluating its body.

Here is an example: when a text scroll window is given a new item generator, which completely changes the text that it should display, it redisplays the window in its bit-save array if necessary.

(defmethod (tv:text-scroll-window :set-item-generator)
	   (new-item-generator)
  (setq item-generator new-item-generator)
  (tv:sheet-force-access (self)
    (send self ':clear-screen)
    (send self ':redisplay 0 
	  (tv:sheet-number-of-inside-lines))))

2.7 Window Locking ¶

Each window or screen has a lock which is used to prevent two processes from operating on the window at once in a way that might cause inconsistent results. Outputting on the window, activating or deactivating the window, exposing or deexposing the window, and changing the window’s shape all lock the window. This is done with process-lock, via tv:lock-sheet. Note that the window’s inferiors must be locked too.

Another form of locking is called "temp-locking". A window is temp-locked when a temporary window (see (temporary-windows)) is exposed on top of it. All the operations which lock the window will have to wait if the window is temp-locked just as they would if the window were locked in the ordinary manner; however, the lock is not considered owned by a process but rather by the temporary windows that overlap the window. It will stay locked until the temporary windows are all deexposed. The :mouse-select operation and some other things know how to deexpose temporary windows when necessary to cause a window to become unlocked.

Special Form: tv:lock-sheet (window-or-screen) &rest body... ¶

Executes body with window-or-screen locked by this process. Calls to tv:lock-sheet are found in wrappers for operations such as :expose, so you need not call it yourself, but you should be aware that it is being done.

.defmetainstvar "windows and screens" tv:lock The lock. It is nil for an unlocked window, a process that has locked the window, or a list of covering temporary windows if this window is "temp-locked". .end_defmetainstvar

.defmetainstvar "windows and screens" tv:lock-count The number of times the lock is locked. This counts the number of recursive lockings for the same process, for example. .end_defmetainstvar

Function: tv:sheet-lock window-or-screen ¶

Returns the contents of window-or-screen’s lock. This is a defsubst and can be setf’d. It is usually unmodular to use this.

Function: tv:sheet-can-get-lock window-or-screen &optional (lock-id current-process) ¶

Returns t if this window or screen could right now be locked by lock-id; essentially, if it is free or already locked that way (but in fact it is more complicated than this.)

Note that if you call this function with inhibit-scheduling-flag nil, you are likely to be susceptible to a timing error.

Function: tv:sheet-clear-locks ¶

Unlocks the locks of all active windows. For use in an emergency.

2.8 Temporary Windows ¶

Normally, when a window is exposed in an area of the screen where there are already some other exposed windows, the windows that used to be there are deexposed automatically by the window system. This is because the window system normally doesn’t leave two windows both exposed if they overlap. (In the absence of temporary windows, which we are about to introduce, the system never allows two overlapping windows to both be exposed.)

But sometimes there are windows that only get put up on the screen for a very short time. The most obvious examples of such windows are the momentary menus that only appear for long enough for you to select an item. It would be unfortunate if every time a momentary menu appeared, the windows under it had to be deexposed. The ones without bit-save arrays would have their screen image destroyed, forcing them to regenerate it or to reappear empty. The ones with bit-save arrays would not be damaged in this way, but they would have to be deexposed, and deexposure is a relatively expensive operation.

This problem is solved for momentary menus by making them temporary windows. Temporary windows work differently from other windows in the following way: when a temporary window is exposed, it saves away the pixels that it covers up. It restores these pixels when it is deexposed. These pixels may come from several different windows. This way it doesn’t mess up the area of the screen that it uses, even if it covers up some windows that don’t have bit-save arrays.

Also, a temporary window, unlike a normal window, does not deexpose the windows that it covers up. This way the covered windows need not try to save their bits away in their bit-save arrays (if they have them) nor ever have to try to regenerate their contents (if they don’t). They never notice that the temporary window was (temporarily) there.

.defflavor tv:temporary-window-mixin This mixin makes a window a temporary window. .end_defflavor

.defmetamethod windows :temporary-bit-array Non-nil if the window is a temporary window. .end_defmetamethod

There would be some problems if temporary windows were this simple. Suppose there is a normal window, and a temporary window appears over it; some of the contents of the normal window are saved in an array inside the temporary window. Now, if the normal window were moved somewhere else, and possibly became deexposed or overlapped by other windows, and then the temporary window were deexposed, the temporary window would dump back its saved bits where the normal window used to be. This would clobber some other window.

Furthermore, even though normal window is still exposed, output on it must not be permitted, since that could overwrite the temporary window.

Because of problems like these, when a temporary window gets exposed on top of some other windows, all the windows that it covers up (fully or partially) become temp-locked. While a window is temp-locked, any attempt to type out on it will wait until it is no longer temp-locked. Furthermore, any attempt to deexpose, deactivate, move, or reposition a temp-locked window will wait until the window is no longer temp-locked. The temp-locking is undone when the temporary window is deexposed.

Because of temp-locking, you should never write a program that will put a temporary window up on the screen for a "long" time. There should be some action by the user, such as moving the mouse, which will make the temporary window deexpose itself. It is best if any attempt by the user to get the system to do something makes the temporary window go away. While the temporary window is in place, it blocks many important window system operations over its area of the screen. The windows it covers cannot be manipulated, and programs that try to manipulate them will end up waiting until the temporary window goes away.

It works fine to have two or more temporary windows exposed at a time. If you expose temporary window a and then expose temporary window b, and they don’t overlap each other, they can be deexposed in either order, and any windows that both of them cover up will be temp-locked until both of them are deexposed. If b covers up a, then a will be temp-locked just like any other window, and so it will not be possible to deexpose a until b has been deexposed.

2.9 The Screen Manager ¶

Sometimes not all of the screen is in use by fully visible windows. This does not happen in elementary use of the Lisp Machine, since the initial windows in the system are all full-screen-sized, but if you create a small Lisp listener with system menu Create the rest of the screen will be unclaimed by any fully visible window. The part of the window system responsible for dealing with unclaimed parts of the screen is called the screen manager.

The screen manager fills such unclaimed areas by looking for deexposed windows which fall entirely or partly within them. Only active immediate inferiors of the screen are considered, and in a specific priority order described in (screen-manager-priority).

A window that falls entirely within unclaimed areas can be made visible without deexposing any other windows. This is called autoexposure. Since the window is a direct inferior of the screen, exposing it always makes it visible. The screen manager goes on considering the remaining deexposed windows, but with less screen area unclaimed.

A window that overlaps the unclaimed areas but also overlaps a visible window cannot simply be exposed. So it becomes partially visible, which means simply that the screen manager copies the appropriate parts of the window’s contents onto the unclaimed areas. The window is not treated as visible or exposed in any other sense. This gives the visual impression of overlapping pieces of paper on a desk top; the deexposed window is partially covered up by the visible windows, but you can still see those parts that aren’t covered. The contents are copied from the window’s bit-save array. Windows without bit-save arrays are by default ineligible for partial visibility, so other windows later in the order will get a chance for the same screen area; however, it is possible to arrange for windows without bit-save arrays to be partially visible (though the displayed contents may not be accurate).

Windows whose size and position are such that they do not fit within the bounds of the superior cannot be exposed, and the screen manager does not try to autoexpose such windows. However, they can be partially visible like any other windows.

The screen manager has one other job. At the same time that it does autoexposure, it can also select a window if there isn’t any selected window at the time. This is called autoselection. A window is a candidate for autoselection if it is an exposed inferior of the screen and its :name-for-selection is non-nil (see (windows-name-for-selection-method)). For more information, see (selection).

The screen manager does not only manage the inferiors of screens; it can manage the inferiors of windows as well. The system invokes the screen manager on a sheet’s inferiors by sending the sheet a :screen-manage message. This happens for all visible sheets regardless of flavor.

.defmetamethod "windows and screens" :screen-manage The default definition of this operation is to do autoexposure and display of partially visible windows among the active inferiors of this window or screen, as described above. .end_defmetamethod

.defflavor tv:no-screen-managing-mixin Prevents the screen manager from dealing with the inferiors of a window by redefining the :screen-manage operation to do nothing.

When a frame is used by a single program, the program usually expects to have sole control over exposure of panes. Then this mixin can be used to tell the screen manager not to interfere. Constraint frames do not normally need to use this mixin because they avoid problems while changing configurations by deactivating any panes that do not belong in the configuration. Zmacs frames do use this mixin so that the screen manager will not autoexpose various editor windows that belong to the frame. .end_defflavor

.defmetamethod "windows and screens" :screen-manage-autoexpose-inferiors Performs autoexposure of the active inferiors of this window or screen. Used by the default definition of :screen-manage. .end_defmetamethod

• Control of Partial Visibility
• Priority among Windows for Exposure
• Delaying Screen Management

3.1 How Programs Select Windows ¶

Programs change the selected window using the :select operation.

.defmetamethod windows :select &optional (remember-previous t) Makes this window (or its selection substitute, if any) the selected window. Unless remember-previous is nil, the previous selected window is entered on the list of previously selected windows for the Terminal and System keys to use.

Many application window flavors define daemons for this operation. Note, however, that the daemons will be run whenever this operation is invoked, even if the window is already selected. .end_defmetamethod

.defflavor tv:select-mixin No window can actually be selected unless its flavor includes this mixin. tv:select-mixin is part of tv:window but not part of tv:minimum-window.

Windows whose flavors do not contain this mixin may be sent :select messages only if they have designated other windows as selection substitutes (see below). The ultimate substitute which is finally selected must have tv:select-mixin. .end_defflavor

.defmetamethod windows :selected-p Returns t if this window is the selected window. .end_defmetamethod

.defmetamethod windows :mouse-select args Selects a window, for a mouse click or for asynchronous keyboard input such as the Terminal command.

While mostly the same as sending :select to the window’s alias for selected windows (see (previously-selected-windows-section)), this operation also causes all type-ahead input to remain with the window that used to be selected (see (tv:kbd-snarf-input-fun)).

Note that the :select and :mouse-select operations should not be invoked in the mouse process. This means that if you want to use them in a :mouse-click or :mouse-buttons or :handle-mouse method, you must do

(process-run-function "Select" window-to-select ':mouse-select)

.end_defmetamethod

.defmetamethod windows :deselect &optional (restore-selected t) This operation is invoked by the window system when a window ceases to be selected. This can be because the window is no longer visible, or because some other window is being selected.

Many application window flavors defined daemons for the :deselect operation.

restore-selected controls what will be done with this window in the tv:previously-selected-windows array used by the Terminal S and System commands, and whether to select automatically some other window found in that array. The possible values are

• :dont-save Do not put the window being deselected into the list anywhere, and do not select any other window.
• nil or :beginning Put the window being deselected at the front of the list, but do not select any other window.
• :end Put the window being deselected at the end of the list, but do not select any other window.
• :first Put the window being deselected at the front of the list, after selecting the window that used to be at the front of the list. This is like what Terminal S does.
• :last or t Put the window being deselected at the end of the list, and select the window at the front of the list. This is the default.

.end_defmetamethod

Function: tv:deselect-and-maybe-bury-window window deselect-mode ¶

Deselects window, selecting the previously selected window. If that causes window to become deexposed, window is buried. deselect-mode is passed to the :deselect operation, where it controls where to put the window in the list of previously selected windows used by the Terminal and System commands.

Special Form: tv:window-call (window [exit-operation exit-args...]) body... ¶

Special Form: tv:window-mouse-call (window [exit-operation exit-args...]) body... ¶

Execute body with window selected. tv:window-call uses the :select operation to do this, while tv:window-mouse-call uses the :mouse-select operation; that is how they differ. On exit, they reselect the window that had been selected before, and send window a message with operation exit-operation and arguments exit-arguments. exit-operation is often :deactivate. It can also be omitted; then nothing is done to window except for deselecting it because some other window is selected.

These constructs are no longer as useful as they once were. For controlling selection among windows of a team, selection substitutes (see (selection-substitutes)) should be used now instead.

3.2 Teams of Windows ¶

The simple paradigm of selection is based on windows that are independent competitors for the user’s input, such as a pair of Lisp listeners. Another frequent situation is a to have a group of windows that act as a team. Usually the windows consist of a single frame and its panes, and usually they are managed by a single process, but neither of these is necessarily so. Often the windows of a team share an input buffer to make it easier for one process to read input from all of the windows at once (see (shared-input-buffers)); this is an important technique which you should definitely read about if you are designing a team of windows.

The simple paradigm extends cleanly to teams if we imagine that the user regards each team as a unit of selection. In this extended paradigm, the user selects among entire teams as if they were single windows.

Teams are not actual Lisp objects, merely concepts understood by the user and programmer. The window system cannot have a selected team; some window of the team must be selected. Each team’s program chooses a window of the team as the team’s selection representative. The selected window should then be the selection-representative of the user’s chosen team. The selected window can change when the user chooses a new team, or when the user’s chosen team picks a new representative.

To implement this, the programmer of the team first picks one window of the team to be the "leader". This is not the same as the selection representative; that can change from moment to moment, but the leader must be fixed. When the team is a frame and its panes, it is natural to make the frame be the leader. Standard mixins are provided to make this easy to do. These mixins and the techniques of using them are described below, and in the following sections.

The selection representative is implemented as the leader’s selection substitute (see (selection-substitutes). Then the team can be selected with the :select operation on its leader window.

Even when the team allows the user some notion of selecting among the windows of the team–such as, when a Zmacs frame in two-window mode allows the user to mouse either of the editor windows to select it– this is implemented most cleanly by starting from the model of a team which does all selection under program control, and defining the appropriate mouse clicks as commands which tell the team’s program to change its selection representative.

Usually you will want to have only a single item appear for the team in the system menu Select option’s menu. If the team consists of a frame which is the leader and its panes, this can be done with tv:inferiors-not-in-select-menu-mixin in the frame’s flavor. More complicated behavior is also possible; for example, Zmacs frames in two-window mode allow each editor window to have its own entry in the Select menu.

Also, Terminal and System commands should reselect the team by selecting its current selection representative. This is done by making them record and reselect the team’s leader. If the team consists of a frame which is the leader and its panes, this can be done with tv:alias-for-inferiors-mixin in the frame’s flavor. (In case you are curious, Zmacs frames follow this pattern exactly. The frame is the alias for any editor windows inside it.)

The following subsections describe the details of how these things are done.

• The System Menu Select Option
• Selection with Terminal and System Commands

3.3 Selection Substitutes ¶

Every window has the ability to designate a "selection substitute". If a window has a substitute, requests to select or deselect the original window will be passed along to the substitute. The substitute may have a substitute of its own, and so on. A window’s selection substitute is remembered in the instance variable tv:selection-substitute, whose value is another window or nil.

.defmetainstvar windows tv:selection-substitute The window’s selection substitute, or nil. .end_defmetainstvar

The main use of selection substitutes is for controlling selection within a team of windows. The team has one window designated as the leader; all user requests to select the team come as :select messages to the team leader as a result of arrangements described in the previous section. As a result, the team’s program can choose a selected window within the team by making it the leader’s selection substitute.

The :alias-for-selected-windows of the substitute window should be the same as that of the window it substitutes for, to avoid paradoxical results from the Terminal command. With a hierarchical team of windows, this is usually arranged by using tv:alias-for-inferiors-mixin in the top window of the team. The substitute window should not appear in the system menu Select menu, for if it did, its entry and the entry for the window it substitutes for would be functional duplicates. tv:inferiors-not-in-select-menu-mixin in the top window of the team serves to prevent the duplicate entry.

These operations on windows are provided for working with selection substitutes:

.defmetamethod windows :selection-substitute Returns this window’s selection substitute, or nil if the window does not currently have one. .end_defmetamethod

.defmetamethod windows :ultimate-selection-substitute Returns this window’s substitute’s substitute... and so on until a window is reached that has no substitute. If this window has no substitute, it itself is returned. .end_defmetamethod

.defmetamethod windows :self-or-substitute-selected-p t if this window, or its substitute, or its substitute’s substitute, etc., is selected. .end_defmetamethod

.defmetamethod windows :set-selection-substitute substitute Sets this window’s selection substitute to substitute (another window or nil). If it was previously the case that this window or its substitute was selected, then the window’s new substitute (or the window itself) will be selected afterward. Thus, the value of :self-or-substitute-selected-p on this window is not changed by this operation. .end_defmetamethod

Note that when the team’s program uses :set-selection-substitute on the team’s leader window to change the selected pane within the team, it does not matter whether the team is currently selected. The "right" results will happen if the team is deselected and reselected at any time.

To switch the selected pane temporarily, use

Special Form: tv:with-selection-substitute (window for-window) body... ¶

Executes body with window as the substitute for for-window. On exit, it sets for-window back to whatever it used to be, and deexposes or deactivates window if appropriate.

Also useful is

Special Form: tv:preserve-substitute-status window body... ¶

Executes body, then selects window if window or its substitute had been selected to begin with.

.defmetamethod windows :remove-selection-substitute window-to-remove suggested-substitute Makes sure that window-to-remove is not this window’s substitute, suggesting suggested-substitute (possibly nil) as a substitute instead. The standard implementation of this operation simply sets the substitute to suggested-substitute if the substitute was window-to-remove. This operation is used and documented so that particular windows can define their own ways of calculating the new value for the substitute, perhaps ignoring suggested-substitute.

When a typeout window is deactivated, this operation is used to make sure that it ceases to be another window’s substitute. .end_defmetamethod

• Non-Hierarchical Selection Substitutes

3.4 The Status of a Window ¶

A window’s status is a keyword that encodes whether the window is selected, whether it is exposed, and whether it is active.

.defmetamethod windows :status Returns one of these symbols:

• :selected Means this is the selected window.
• :exposed Means this is exposed but not selected. It may not be visible.
• :exposed-in-superior Means this window is exposable but its superior has no screen array.
• :deexposed Means this window is active in its superior but not exposable.
• :deactivated Means this window is not even active.

.end_defmetamethod

.defmetamethod windows :set-status status Restores the window’s status to status, by selecting or deselecting, exposing or deexposing, and activating or deactivating, as necessary. status must be one of the possible values of the :status operation.

The :status and :set-status operations are useful for selecting a window temporarily and then restoring everything as it was. :set-status is correct for this because it may be necessary to deexpose the window or deactivate it in addition to deselecting it. .end_defmetamethod

3.5 Windows and Processes ¶

A self-contained interactive system that has its own window(s) usually has its own process to drive the windows. Peek, Zmacs, ZMail and the inspector all do this when invoked through the System key. Usually each window you create has its own process; there is a Peek process for each Peek window, so different Peek windows run completely independently.

Whether a window is managed by a dedicated process or by various processes is not a crucial decision. The program that reads commands from the window and draws on the window can always be run in one dedicated process, or in different processes at different times (though if you run it in two processes at once, you had better be careful to keep them from confusing each other). The mechanisms of selection and exposure that control whether input and output are possible on a window at a given time work automatically on any process(es) that try to do the input or output. So when there is a dedicated process for a window, often the only connection between them is that the dedicated process is running a program that has a pointer to that window (typically the value of terminal-io in the process is that window).

For example, the inspector you get with System I has a dedicated process, whereas the one you get by calling inspect runs in the process that inspect is called in. Yet these two windows have the same flavor, and the same function, tv:inspect-command-loop, does the main work. The only differences are in deciding when to deexpose the window, what to do when that happens, when it can be reused, what to do if the user types End, and other things related directly to the difference in the two user interfaces for entering and exiting.

The inspector makes an instructive example for comparing these two ways of managing a window. The function inspect allocates a window out of a resource of reusable windows of the right flavor (see defresource, (defresource-fun)). It sends the window some messages to initialize it for this particular session of use; this is how it tells the window about the object that is the argument to inspect. Then it selects the window manually using tv:window-call (see (tv:window-call-fun)) and calls the inspector program. When the user types End, the program returns, tv:window-call reselects the old window and deactivates the inspect window, and inspect returns. inspect uses an unwind-protect so that aborting outside of inspect for any reason brings back the old window.

Typing System I finds or creates an an inspect window of the same flavor. When no init options are specified, this flavor’s default init plist specifies the creation of a process, which is initialized to call the inspector program. If the user types End and the inspector command loop returns, the top-level function in the dedicated process buries the inspector window and loops back to the beginning. That’s all that is necessary to make System I work. The resource that inspect uses explicitly specifies an init option when it constructs a window, so that no process is made.

.defflavor tv:process-mixin Provides an instance variable tv:process which can remembers a process associated with the window. A window that will sometimes be used with a dedicated process should have this mixin.

The most valuable service that this flavor provides is an easy way to create and initialize a process for each window that is created, and inform the process which window it was created for. Once this is done, for the most part the desired results follow without special effort.

Selecting the window or making it visible will give the process a run reason. The window itself is used as the run reason. Also, this will reset the process if it is flushed (waiting with false as its wait function).

The :kill operation on the window will invoke the :kill operation on the process.

Use of tv:process-mixin guarantees that the :process operation will return the explicitly specified process, regardless of which process has most recently read from the window. .end_defflavor

.definstvar tv:process-mixin tv:process The process associated with the window, or nil. .end_definstvar

.definitoption tv:process-mixin :process process-or-description Specifies the process for this window. The argument can be a process, or it can be a list, which is used as a description for creating a process. The list looks like

(initial-function make-process-options)

When the process starts up, it will call initial-function with the window as its sole argument. Usually the initial function should bind terminal-io to the argument.

If this option is omitted or nil, the window starts out without a process. .end_definitoption

.defmethod tv:process-mixin :process .defmethod1 tv:process-mixin :set-process process Gets or sets the process associated with this window. nil is a legal value, which means that the window has no process associated with it, even though it has the ability to have one. .end_defmethod

.defmetamethod windows :processes Returns a list of processes dedicated to this window. :append method combination is used, so that all the processes mentioned by any of the methods are put into the final answer. These are the processes that the :kill operation will kill.

The default is to return nil. tv:process-mixin contributes a suitable method. .end_defmetamethod

These process-related operations are defined on tv:select-mixin so that they are always supported by the selected window. Since windows lacking tv:process-mixin do not explicitly remember a process, a heuristic is used to come up with a process to operate on: it is the last process to have read input from this window’s input buffer. (Think about the fact that the input buffer may be shared with other windows.)

tv:process-mixin is always put before tv:select-mixin in the components of a window flavor, so this method will be overridden.

.defmethod tv:select-mixin :process Gets a process somehow associated with this window, heuristically if necessary. .end_defmethod

.defmethod tv:select-mixin :set-process process Records process in the place where the last process to read input from this window would normally be recorded. .end_defmethod

.defmethod tv:select-mixin :arrest .defmethod1 tv:select-mixin :un-arrest Arrests or unarrests the process returned by the :process operation. The arrest reason used or revoked is not specified (it defaults). .end_defmethod

.defmethod tv:select-mixin :call Selects an idle Lisp listener window (possibly this window, if it is an idle Lisp listener). If the window selected is not this one, arrest this window’s process with arrest reason :call. This arrest reason is removed automatically by selecting this window again. .end_defmethod

.defflavor tv:reset-on-output-hold-mixin Causes any process that tries to draw on this window when it has an output hold to be reset when it does so (see the :reset operation on processes, (si:process-reset-method)). .end_defflavor

.defflavor tv:truncating-pop-up-text-window-with-reset A temporary window that truncates lines and also resets processes that try to output on it when it has output hold. This flavor is what Terminal F uses. .end_defflavor

4.1 Init Options for Sizes and Positions ¶

.defmetainitoption windows :left left-edge .defmetainitoption1 windows :x left-edge .defmetainitoption1 windows :top top-edge .defmetainitoption1 windows :y top-edge .defmetainitoption1 windows :position (left-edge top-edge) .defmetainitoption1 windows :right right-edge .defmetainitoption1 windows :bottom bottom-edge .defmetainitoption1 windows :width outside-width .defmetainitoption1 windows :height outside-height .defmetainitoption1 windows :size (outside-width outside-height) .defmetainitoption1 windows :inside-width inside-width .defmetainitoption1 windows :inside-height inside-height .defmetainitoption1 windows :inside-size (inside-width inside-height) .defmetainitoption1 windows :edges (left-edge top-edge right-edge bottom-edge) These options set various position and size parameters. The size and position of the window are computed from the parameters provided by these and other options, and the set of defaults described above. Note that all edge parameters are relative to the outside of the superior window. .end_defmetainitoption

.defmetainitoption windows :character-width spec This is another way of specifying the width. spec is either a number of characters or a character string. The inside width of the window is made to be wide enough to display those characters, or that many characters, in font zero. .end_defmetainitoption

.defmetainitoption windows :character-height spec This is another way of specifying the height. spec is either a number of lines or a character string containing a certain number of lines separated by carriage returns. The inside height of the window is made to be that many lines. .end_defmetainitoption

.defmetainitoption windows :integral-p t-or-nil The default is nil. If this is specified as t, the inside dimensions of the window are made to be an integral number of characters wide and lines high, by making the bottom margin larger if necessary. .end_defmetainitoption

.defmetainitoption windows :edges-from source Specifies that the window is to take its edges (position and size) from source, which can be one of:

• a list The elements of the list should be the four edges, left, top, right and bottom, all relative to this window’s superior.
• a string The inside-size of the window is made large enough to display the string, in font zero.
• a list (left-edge top-edge right-edge bottom-edge) Those edges, relative to the superior, are used, exactly as if you had used the :edges init-option (see above).
• :mouse The user is asked to point the mouse to where the top-left and bottom-right corners of the window should go. (This is what happens when you use the Create command in the system menu, for example.)
• a window That window’s edges are copied.

.end_defmetainitoption

.defmetainitoption windows :minimum-width n-pixels .defmetainitoption1 windows :minimum-height n-pixels In combination with the :edges-from :mouse init option, these options specify the minimum size of the rectangle accepted from the user. If the user tries to specify a size smaller than one or both of these minima, he will be beeped at and prompted to start over again with a new top-left corner. .end_defmetainitoption

The group of operations below is used to examine or change the size or position of a window. Many operations that change the window’s size or position take an argument called option. The reason that this argument exists is that certain new sizes or positions are not valid. One reason that a size may not be valid is that it may be so small that there is no room for the margins; for example, if the new width is smaller than the sum of the sizes of the left and right margins, then the new width is not valid. A new setting of the edges is also invalid if the window is exposed and the new edges are not enclosed inside its superior. In all of the operations that take the option argument, option may be either nil or :verify. nil means that you really want to set the edges, and if the new edges are not valid, an error should be signalled. :verify means that you only want to check whether the new edges are valid or not, and you don’t really want to change the edges. If the edges are valid, the operation with :verify returns t; otherwise it returns two values: nil and a string explaining what is wrong with the edges. (Note that it is valid to set the edges of a deexposed inferior window in such a way that the inferior is not enclosed inside the superior; you just can’t expose it until the situation is remedied. This makes it more convenient to change the edges of a window and all of its inferiors sequentially; you don’t have to be careful about what order you do it in.)

4.2 Flavor Operations for Sizes and Positions ¶

.defmetamethod windows :size Returns two values, the outside width and outside height. .end_defmetamethod

.defmetamethod windows :height .defmetamethod1 windows :width Return the window’s height or its width. .end_defmetamethod

.defmetamethod windows :set-size new-width new-height &optional option Sets the outside width and outside height of the window to new-height and new-width, without changing the position of the upper-left corner. .end_defmetamethod

.defmetamethod windows :inside-size Returns two values, the inside width and the inside height. .end_defmetamethod

.defmetamethod windows :inside-height .defmetamethod1 windows :inside-width Return the inside height of the window or the inside width. .end_defmetamethod

.defmetamethod windows :set-inside-size new-inside-width new-inside-height &optional option Set the inside width and inside height of the window to new-inside-height and new-inside-width, without changing the position of the upper-left corner. The margin sizes are recomputed according to their contents, which in simple cases means they will stay the same. .end_defmetamethod

.defmetamethod windows :position Returns two values, the x and y positions of the upper-left corner of the window, in pixels, relative to the superior window. .end_defmetamethod

.defmetamethod windows :set-position new-x new-y &optional option Sets the x and y position of the upper-left corner of the window, in pixels, relative to the superior window. .end_defmetamethod

.defmetamethod windows :edges Returns four values, the left, top, right, and bottom edges, in pixels, relative to the superior window. .end_defmetamethod

.defmetamethod windows :set-edges new-left new-top new-right new-bottom &optional option Sets the edges of the window to new-left, new-top, new-right, and new-bottom, in pixels, relative to the superior window. .end_defmetamethod

.defmetamethod windows :inside-edges Returns four values, the left, top, right, and bottom inside edges, in pixels, relative to the top-left corner of this window. This can be useful for clipping. Note that this operation is not analogous to the :edges operation, which returns the outside edges relative to the superior window. .end_defmetamethod

.defmetamethod windows :center-around x y Without changing the size of the window, positions the window so that its center is as close to the point (x,y) as is possible without hanging off an edge. The coordinates are in pixels relative to the superior window. .end_defmetamethod

.defmetamethod windows :expose-near mode &optional (warp-mouse-p t) If the window is not exposed, changes its position according to mode and exposes it (with the :expose operation; see (windows/ and/ screens-expose-method)). If it is already exposed, does nothing.

mode should be a list; it may be any of the following:

• (:point x y) Position the window so that its center is as at the point (x,y), in pixels, relative to the superior window, or as close as possible without hanging off an edge of the superior.
• (:mouse) This is like the :point mode above, but the x and y come from the current mouse position instead of the caller. This is like what pop-up windows do. In addition, if warp-mouse-p is non-nil, the mouse is warped (see (warp)) to the center of the window. (The mouse moves only if the window is near an edge of its superior; otherwise the mouse is already at the center of the window.)
• (:rectangle left top right bottom) The four arguments specify a rectangle, in pixels, relative to the superior window. The window is positioned somewhere next to but not overlapping the rectangle. In addition, if warp-mouse-p is non-nil, the mouse is warped (see (warp)) to the center of the window.
• (:window window-1 window-2 window-3 ...) Position the window somewhere next to but not overlapping the rectangle that is the bounding box of all the window-ns. You must provide at least one window. Usually you only give one, and this means that the window is positioned touching one edge of that window. In addition, if warp-mouse-p is non-nil, the mouse is warped (see (warp)) to the center of the window.

.end_defmetamethod

.defmetamethod windows :change-of-size-or-margins &rest options This is the primitive operation for changing a window’s size or the size of its margins. All the other operations to do so end up calling this one, after all error checking has been done.

This operation should not be called by users; to change the size, use :set-size or another higher-level operation, and the margin sizes should be managed by the flavors that are responsible for computing how big they should be (tv:borders-mixin, etc.).

However, this operation is a good place to add :after daemons to recompute other data structure or change the size of inferiors according to the window’s new size. In the :after daemon, the window’s size and margins will already be altered to their new values. .end_defmetamethod

4.3 Low Level Edges Functions ¶

.defmetainstvar windows tv:x-offset .defmetainstvar1 windows tv:y-offset The position of the window’s outside left (or top) edge relative to the window’s superior. .end_defmetainstvar

.defmetainstvar windows tv:width .defmetainstvar1 windows tv:height The total width or height of the window. .end_defmetainstvar

Recall that a sheet is either a window or a screen.

Function: tv:sheet-width window ¶

Function: tv:sheet-height window ¶

Function: tv:sheet-x-offset window ¶

Function: tv:sheet-y-offset window ¶

Return the value of the corresponding instance variable of window. These are accessor defsubsts created by the :outside-accessible-instance-variables option of defflavor. They can therefore be setf’d, but doing so is usually unwise.

Function: tv:sheet-inside-width &optional (window self) ¶

Function: tv:sheet-inside-height &optional (window self) ¶

Return the inside width or height of the window.

When used without an argument, these defsubsts refer directly to the instance variables, and therefore must be called from methods or functions which use (declare (:self-flavor ...)).

Function: tv:sheet-number-of-inside-lines &optional (window self) ¶

Returns the number of lines (of height equal to tv:line-height) that fit in the inside height of the window.

When used without an argument, these defsubsts refer directly to the instance variables, and therefore must be called from methods or functions which use (declare (:self-flavor ...)).

Function: tv:sheet-calculate-offsets window superior ¶

Returns the x and y positions of window’s upper left corner in superior as two values. window must be an indirect inferior of superior, zero or more levels down. If window and superior are the same window, the values are zero.

Function: tv:sheet-overlaps-p sheet left top width height ¶

Function: tv:sheet-overlaps-edges-p sheet left top right borrom ¶

t if sheet overlaps the specified rectangle. The edges specified are relative to sheet’s superior.

Function: tv:sheet-overlaps-sheet-p sheet-a sheet-b ¶

t if the two sheets overlap. This is a geometrical test, and it does not matter where in the hierarchy the two sheets are.

Function: tv:sheet-within-p sheet left top right bottom ¶

t if sheet is contained within the specified rectangle, given relative to sheet’s superior.

Function: tv:sheet-within-sheet-p sheet outer-sheet ¶

t if sheet is within outer-sheet’s area. This is a geometrical test, and it does not matter where in the hierarchy the two sheets are.

Function: tv:sheet-bounds-within-sheet-p left top width height outer-sheet ¶

t if the specified rectangle is within outer-sheet. The edges are specified relative to outer-sheet’s superior.

Function: tv:sheet-contains-sheet-point-p sheet top-sheet x y ¶

t if sheet contains the point (x,y) in top-sheet.

5.1 Input Buffers ¶

Every window that generates input or from which input is read must have an input buffer that holds characters that are typed by the user before any program reads the characters. When you type a character, it enters the selected window’s buffer. (This is not precisely true, but it’s a good first mental model. See (io-buffer).) Reading input from a window, with the :tyi operation for example, takes objects out of the window’s input buffer. tv:stream-mixin gives the window an input buffer, but some other flavors (such as command menus) provide an input buffer without tv:stream-mixin. The input buffer lives in an instance variable of the window, called tv:io-buffer.

Input buffers are examples of I/O buffers, which are a general facility provided by the window system. You can explicitly manipulate input buffers in order to get certain advanced functionality, by using the :io-buffer init-option and the :io-buffer and :set-io-buffer operations. Another thing you can do is put properties on the I/O buffer’s property list; this lets you request various special features. I/O buffers are explained on (io-buffer).

A window can be thought of as generating input when the keyboard is used while the window is selected. This is the way that ordinary characters normally get into the input buffer. But input can be generated at any place in the program by means of the :force-kbd-input operation. For example, mouse clicks are often handled by forcing input which is read by the window’s command-interpreting process (see (tv:list-mouse-buttons-mixin-flavor)). Then we say that the mouse click also generates input.

All the input, no matter how generated, ends up mixed together in the same input buffer, in chronological order. All the input operations take input from the buffer in that order.

Normally each window that can generate input has its own input buffer. If a process is managing more than one window that can generate input, a program to look for input from all the windows at once would be cumbersome. So it is not done this way. Instead, all the windows are made to share a single input buffer. Then all input generated by all of the windows goes into that buffer, from which the input can be read through any one of the windows. The program simply reads input from one of the windows–always the same one, if the programmer prefers–and gets all the input intended for it. All the keyboard input directed at it, and all mouse clicks on its windows, get merged into a single chronological input stream.

The input buffer does not record which window was "responsible" for generating input read from a shared input buffer. For mouse clicks the program may need to know which window the mouse was clicked on in order to obey the command properly. The standard way to pass this information is to use a list as the input character and make the window clicked on one of the elements of the list.

The window(s) used for input operations must have tv:stream-mixin. The other windows need only be able to put input into the right input buffer. It is often easiest to use tv:stream-mixin for them as well, and generate the input with :force-kbd-input. However, it is sufficient for such windows to support the :io-buffer operation by returning the correct shared input buffer, and put the input they generate into that buffer in any way that works, such as with the function tv:io-buffer-put, or by invoking :force-kbd-input on another window known to have tv:stream-mixin and to share the same input buffer.

If a frame includes a pane that is handled by its own process (such as a Zmacs frame), that pane should not share the input buffer used by the rest of the panes. In general, there should be one input buffer for each process you are using, and that input buffer should be shared by the windows which go with that process.

In general, the way to make windows share an input buffer is to create one using tv:make-default-io-buffer and then specify it for the :io-buffer init keyword when each pane is created. There are also frame flavors that automatically make the panes share an input buffer.

.definstvar tv:stream-mixin tv:io-buffer The window’s input buffer. .end_definstvar

.definitoption tv:stream-mixin :io-buffer spec Initializes the input buffer of the window. spec may be an I/O buffer, a number or a list. If it is a number, an I/O buffer is made with that size, no input function, and the default output function. If it is a list, it is interpreted as

(size input-function output-function)

but if the output-function is nil or omitted, tv:kbd-default-output-function is used. .end_definitoption

.defmethod tv:stream-mixin :io-buffer .defmethod1 tv:stream-mixin :set-io-buffer io-buffer Return or set the window’s input buffer. .end_defmethod

5.2 Blips ¶

Input need not be made of characters; lists are often used as well for program-generated input, especially for representing mouse clicks in different kinds of mouse-sensitive areas. "Characters" which are lists are called blips. The car of the list is by convention a symbol which identifies the kind of blip. Look for "blip types" in the concept index to find the places in this manual that define various kinds of blips.

Caution: when using blips, you should keep in mind that the blips may be discarded if the process has called any function that does not know what to do with them. The debugger and break are such functions, so this can happen at any time. Blips either should describe mouse actions, which can safely be ignored if they happen when they are not meaningful, or should notify the process to check other data structures. A blip should not be used to indicate a request or response from another process, since this information must not be lost. Instead, put the data on a separate queue and have the process check the queue after every command. A blip that executes as a no-op command will serve to wake the process up if it is waiting for input when the data goes on the queue.

There is a technique you can use to cause blips to be handled even in the middle of calls to read, the debugger, and other programs that do not look for blips. It is to give your window flavor an :around method for :any-tyi. This :around method can look at the value being returned; if it is one of certain types of blips, you can handle it and then loop around, calling the original :any-tyi handler again without returning to the caller. If it is anything else, you just return it.

5.3 Stream Input Operations ¶

.defmethod tv:stream-mixin :any-tyi &optional eof-action Reads and returns the next character of input from the window, waiting if there is none. The character comes from the window’s input buffer if it contains any characters; otherwise, it comes from the keyboard. eof-action is ignored since "end-of-file" is not meaningful for windows; this argument exists only because it is part of the input stream protocol. .end_defmethod

.defmethod tv:stream-mixin :tyi &optional eof-action Like :any-tyi but throws away any blips ("characters" which are lists) that it receives. It keeps on reading until it finds an actual character, and returns that. Discarded blips will never be seen as input. .end_defmethod

.defmethod tv:stream-mixin :any-tyi-no-hang &optional eof-action Like :any-tyi if input is already present in the buffer, but returns nil right away if the buffer is empty. This is used by programs that continuously do something until a key is typed, then look at the key and decide what to do next. .end_defmethod

.defmethod tv:stream-mixin :tyi-no-hang &optional eof-action Like :any-tyi but throws away any blips ("characters" which are lists) that it receives. It keeps on reading until it finds an actual character or the buffer empty; then it returns the character or nil. Discarded blips will never be seen as input. .end_defmethod

.defmethod tv:stream-mixin :mouse-or-kbd-tyi .defmethod1 tv:stream-mixin :mouse-or-kbd-tyi-no-hang These are like the :tyi and :tyi-no-hang operations, except that blips of a certain kind are not discarded and do count as input. These are blips whose car is the symbol :mouse-button. In this case, the first value returned is the third element (caddr) of the blip, and the second value returned is the whole blip. By convention, the third element of such a blip is a character whose %%kbd-mouse bit is 1, which identifies the button that the user clicked (see (mouse-blip)). All other blips are discarded, as they are by :tyi and :tyi-no-hang. The first value is always a fixnum. .end_defmethod

.defmethod tv:stream-mixin :list-tyi This is the "opposite" of :tyi. It returns only blips and discards real characters. .end_defmethod

.defmethod tv:stream-mixin :untyi character Put character back into the window’s input buffer so that it will be the next character returned by :tyi. Note that character must be exactly the last character that was read, and that it is illegal to do two :untyi’s in a row. This is used by parsers that look ahead one character, such as read. .end_defmethod

.defmethod tv:stream-mixin :force-kbd-input input input is inserted into the window’s input buffer, to be read by the :tyi or other input operation in its turn. input may be a character or a list (a blip). It may also be a string; then all the characters of the string are forced as input, one by one.

This is the standard way that blips are put into the input stream (see (blips)). .end_defmethod

.defmethod tv:stream-mixin :listen Returns t if there are any characters available to :tyi, or nil if there are not. For example, the editor uses this to defer redisplay until it has caught up with all of the characters that have been typed in. .end_defmethod

.defmethod tv:stream-mixin :wait-for-input-with-timeout timeout Waits until either input is available or timeout 60ths of a second have elapsed. .end_defmethod

.defmethod tv:stream-mixin :clear-input Clears this window’s input buffer. This flushes all the characters that have been typed at this window, but have not yet been read. .end_defmethod

.defmethod tv:stream-mixin :playback Returns an array describing the last n characters read from this window, for some value of n (which is the size of the array). The array elements are used in a circular fashion, the last one being followed by the first one, and array leader element 1 contains the index of the last slot stored into (the one containing the last character read). The editor command Help L uses this operation. .end_defmethod

.defmethod tv:stream-mixin :rubout-handler options function &rest args Applies function to args inside an environment where inputting from this window will echo the characters typed and provide for simple input editing. This is documented in more detail in the Lisp Machine manual.

options is an assq list of keyword symbols and arguments to them. The options acceptable to windows are:

• :full-rubout flag If the user rubs out all of the characters that he has typed in, normally the rubout-handler just waits for more characters. If the :full-rubout option is supplied, the rubout handler returns to the caller in this situation. Two values are returned, nil and flag.
• :initial-input string Treat the characters in string as typeahead before reading anything from the keyboard.
• :pass-through ch1 ch2... Treat the characters ch1, ch2, etc. as ordinary characters even if they would normally be special commands to the rubout-handler.
• :prompt function function is a function to be called before reading any characters; typically it will display a prompt. The arguments to function are the window and a flag. When the rubout-handler is first entered the flag is nil, but if it is necessary to prompt again, for instance if the user cleared the screen, function is called with the character the user typed (e.g. #\clear-screen) as its flag argument.

  function can also be a string; then it is simply printed as the prompt.

• :reprompt function The same as :prompt except that the function is not called the first time through. If both :prompt and :reprompt are used, the :prompt is used the first time and the :reprompt is used on reprinting.

.end_defmethod

.defmethod tv:stream-mixin :save-rubout-handler-buffer Returns a description of the rubout handler buffer’s contents, and clears it out. Two values are returned: a string and a fixnum (which is the current cursor index in the string). This is used on entry to the function break so that typing the Break key interfaces properly with rubout handling. .end_defmethod

.defmethod tv:stream-mixin :restore-rubout-handler-buffer string index Loads the rubout handler buffer contents from string and sets the cursor position to index. The arguments are usually two values obtained from :save-rubout-handler-buffer. .end_defmethod

.defmethod tv:stream-mixin :refresh-rubout-handler &optional discard-last-character Requests the rubout handler to reprint its buffer and reprompt. If discard-last-character is non-nil, the last character in the buffer is discarded first. This is used by :restore-rubout-handler-buffer.

If you are reading input using the rubout handler, but want to process certain characters immediately (perhaps the character Help) and not leave them as part of the ordinary input, use this operation with argument t. .end_defmethod

.defflavor tv:preemptable-read-any-tyi-mixin This flavor defines the :preemptable-read operation. .end_defflavor

.defmethod tv:preemptable-read-any-tyi-mixin :preemptable-read options function &rest arguments You may have noticed that in the inspector and in the Window Error Handler, if you start typing in a Lisp expression, and then while in the middle of typing it you use the mouse to select an object by pointing at it, the program sees the object you moused. If nothing special were done, though, the blip sent by the mouse process would get put at the end of the input buffer and would not be seen because of the characters that you have typed. This mixin is what is used to solve the problem.

The :preemptable-read operation takes the same arguments as the normal :rubout-handler operation, and does the same thing if the mouse is not used. (In fact, it has nothing to do with the read function, despite the name.) The difference is that if any blip is sent to the window, the operation returns the blip as the first value and the symbol :mouse-char as the second value. (It does this even if the blip did not come from the mouse; most blips do.) The characters that were in the rubout-handler buffer when the blip arrived will come back the next time a :preemptable-read operation is used, so the user can keep typing his expression in. .end_defmethod

These obsolete functions are still used in some old code:

Function: kbd-tyi ¶

Performs :tyi on terminal-io.

Function: kbd-tyi-no-hang ¶

Performs :tyi-no-hang on terminal-io.

Function: kbd-char-available ¶

Performs :listen on terminal-io.

5.4 I/O Buffers ¶

An I/O buffer is an array of fixed size used as a ring buffer. Typically, characters are put into the buffer by one process and removed by another in FIFO order. The process that is removing characters can wait if the buffer is empty, and a process putting in characters can wait if the buffer is full (or it could throw away the characters). Each window with tv:stream-mixin has an input buffer which is an I/O buffer, and there is also one global I/O buffer for the keyboard itself.

Note that the things stored in an I/O buffer can be any Lisp objects. They do not have to be characters, in any sense. But in practice I/O buffers are in fact used for storing characters (which may be lists), so that is how this section is written.

An I/O buffer has these slots in its leader.

• tv:io-buffer-size The number of slots in the input buffer.
• tv:io-buffer-input-pointer The index at which the next character inserted should be stored.
• tv:io-buffer-output-pointer The index at which the next available character is present.

  If the input and output pointers are equal, the buffer is empty. If the output pointer points at the slot after the input pointer, the buffer is considered full (in fact, one slot is still empty. It cannot be used).

• tv:io-buffer-output-function A function to be called when characters are removed, or nil. It is called with the buffer and the character as arguments. Its value should be a translated version of the character (this is usually the same as the argument). It can also return a non-nil second character, which says that the character should be discarded. In this case, tv:io-buffer-get will remove the following character, or wait for one.

  In window input buffers this is usually a function that checks for and handles synchronous interception.

• tv:io-buffer-input-function A function to be called when characters are inserted, or nil. The window system does not actually use this feature. The calling conventions are the same as for the output function.
• tv:io-buffer-state This may be set to t, nil, :input or :output to control what can be done with the buffer. Characters can be put in if this is nil or :input, and can be removed if this is nil or :output.
• tv:io-buffer-plist A property list containing various properties.
• tv:io-buffer-last-input-process The last process that put a character in this I/O buffer.
• tv:io-buffer-last-output-process The last process that removed a character from this I/O buffer.
• tv:io-buffer-record An array that records the last n characters read from this I/O buffer, for some fixed n. This array too is a ring buffer, but nothing is ever "removed" from it; after it is full, it contains the last n things stored into it. The accessor tv:io-buffer-record-pointer gets the index of the last slot stored into.

Function: tv:io-buffer-empty-p io-buffer ¶

Function: tv:io-buffer-full-p io-buffer ¶

Non-nil if the buffer is empty, or full.

Function: tv:make-io-buffer size input-function output-function plist state ¶

Creates and returns an I/O buffer, initializing some of the slots from its arguments and the others in a default or reasonable fashion. The buffer is initially empty.

Function: tv:io-buffer-put buffer character &optional no-hang-p ¶

Inserts character into buffer, waiting if it is full unless no-hang-p. This function also waits if the buffer’s state does not permit input. It returns t if the character was inserted.

Function: tv:io-buffer-get buffer &optional no-hang-p ¶

Removes the next character from buffer. If the buffer is empty, normally we wait for a character to appear, but if no-hang-p is non-nil we return nil immediately. This function also waits if the buffer’s state does not permit output. The character removed is put in buffer’s io-buffer-record array.

Function: tv:io-buffer-unget buffer character ¶

Inserts character into buffer as the next character to be removed rather than as the last one to be removed. This is used for undoing tv:io-buffer-get, and it is an error if character does not match the last character removed. character is removed from the io-buffer-record array, by backing up its pointer, just to avoid duplication when character is read a second time.

This function should not be used more than once between input operations.

Function: tv:io-buffer-push buffer character ¶

Inserts character into buffer as the next character to be removed; that is, in a LIFO manner. This is as opposed to tv:io-buffer-put which inserts a character at the end.

Function: tv:io-buffer-clear buffer ¶

Makes buffer empty.

Function: tv:process-typeahead buffer function ¶

Uses function as a filter for the characters in buffer. function is called once for each character, with the character as its sole argument. If function returns non-nil, that value is stored back in the buffer instead of the original character. If function returns nil, the character is deleted from the input buffer.

• I/O Buffers and Type Ahead
• I/O Buffers as Input Buffers

5.5 Intercepted Characters ¶

There are several characters that are specially intercepted by the window system. Some are intercepted when a process tries to read them, and some are intercepted as soon as they are typed. The first kind are called synchronously intercepted characters and the second are called asynchronously intercepted characters. The latter come in two kinds: global asynchronous characters such as Terminal and System which are always available (see (global-asynchronous-characters)), and others defined by the selected window, normally including Control-Abort and so on (see (asynchronous-intercepted-characters)).

• Synchronously Intercepted Characters
• Asynchronously Intercepted Characters
• Global Asynchronous Characters

((#\c-abort tv:kbd-asynchronous-intercept-character
  (:name "Abort" :priority 50.)
  tv:kbd-intercept-abort)
 (#\c-m-abort tv:kbd-asynchronous-intercept-character
  (:name "Abort All" :priority 50.)
  tv:kbd-intercept-abort-all)
 (#\c-break tv:kbd-asynchronous-intercept-character
  (:name "Break" :priority 40.)
  tv:kbd-intercept-break)
 (#\c-m-break tv:kbd-asynchronous-intercept-character
  (:name "Error Break" :priority 40.)
  tv:kbd-intercept-error-break))

(character handler-function . additional-args)

5.6 Polling The Keyboard Explicitly ¶

Another way of using the keyboard, different from reading a stream of input characters from a window, is to treat it as a "random access" device and look at the instantaneous state of particular keys. Spacewar does this.

Function: tv:key-state key-name ¶

Returns t if the keyboard key named key-name is currently depressed, nil if it is not.

key-name may be the symbolic name of a shift key, from the table below, or the character code of a non-shift key, which is the character you get when you type that key without any shifts: a lower-case letter, a digit, or a special character. Shift keys that come in pairs have three symbolic names; one for the left-hand key, one for the right-hand key, and one for both, which is considered to be depressed if either member of the pair is. The shift key names are:

:shift		:left-shift		:right-shift
:greek		:left-greek		:right-greek
:top		:left-top		:right-top
:control	:left-control		:right-control
:meta		:left-meta		:right-meta
:super		:left-super		:right-super
:hyper		:left-hyper		:right-hyper
:caps-lock	:alt-lock		:mode-lock
:repeat

6.1 How A Character Is Printed ¶

Typing out a character does more than just drawing the character on the screen. The cursor position is moved to the right place; non-printing characters are dealt with reasonably; if there is an attempt to move off the right or bottom edges of the screen, the typeout wraps around appropriately; more breaks are caused at the right time if more processing is enabled. Here is the complete explanation of what typing out a character does. You may want to remind yourself how the Lisp Machine character set works; see (character-set). You don’t have to worry much about the details here, but in case you ever need to know, here they are. If you aren’t interested, skip ahead to the definitions of the operations.

First, any output exceptions that are present are dealt with, and made to go away. See (output-exceptions), for an explanation of this.

When all exceptions have been dealt with, the character finally gets typed out. If it is a printing character, it is typed in the current font at the cursor position and the cursor position is moved to the right by the width of the character. If it is one of the format effectors #\return, #\tab, and #\backspace, it is handled in a special way to be described in a moment. All other special characters have their names typed out in tiny letters surrounded by a lozenge, and the cursor position is moved right by the width of the lozenge. If an undefined character code is typed out, it is treated like a special character; its code number is displayed in a lozenge.

#\tab moves the cursor position to the right to the next tab stop, moving at least one character-width. Tab stops are equally spaced across the window. The distance between tab stops is tab-nchars times the character-width of the window. tab-nchars defaults to 8 but can be changed (see (windows-tab-nchars-init-option)).

Normally #\return moves the cursor position to the inside left edge of the window and down by one line-height, and clears the line (see (windows-clear-eol-method)). It also deals with more processing and the end-of-page condition as described above. However, if the window’s cr-not-newline-flag is on, the #\return character is not regarded as a format effector and is displayed as "return" in a lozenge, like other special characters.

If the character being typed out is a #\backspace, the result depends on the value of the window’s backspace-not-overprinting-flag. If the flag is 0, as is the default, the cursor position is moved left by one character-width (or to the inside left edge, whichever is closer). If the flag is 1, #\backspaces are treated like all other special characters.

6.2 Stream Output Operations ¶

.defmetamethod windows :tyo ch &optional font Type ch on the window, as described above. Basically, type the character ch in font or the current font at the cursor position, and advance the cursor position. .end_defmetamethod

.defmetamethod windows :string-out string &optional (start 0) (end nil) Type string on the window, starting at the character start and ending with the character end. If end is nil, continue to the end of the string; if neither optional argument is given, the entire string is typed. This behaves exactly as if each character in the string (or the specified substring) were printed with the :tyo operation, but it is much faster. .end_defmetamethod

.defmetamethod windows :fat-string-out string &optional (start 0) (end nil) Type the fat string string on the window. This is like :string-out except that the %%ch-font field of each character is used as the font to draw that character in. The window’s current font is not used. .end_defmetamethod

.defmetamethod windows :line-out string &optional (start 0) (end nil) Do the same thing as :string-out, and then advance to the next line (like typing a #\return character). The main reason that this operation exists is so that the stream-copy-until-eof function (see (stream-copy-until-eof-fun)) can, under some conditions, move whole lines from one stream to another; this is more efficient than moving characters singly. The behavior of this operation is not affected by the :cr-not-newline-flag init-option (see (windows-cr-not-newline-flag-init-option)). .end_defmetamethod

.defmetamethod windows :string-out-centered string left right y-pos Output string (or the portion from start to end), centered between x positions left and right, at y position y-pos (which defaults to the current cursor position). The cursor is left at the end of the string. If the string is multiple lines, the entire rectangular shape it occupies is centered as a unit. To center lines individually, output each line individually with this operation. .end_defmetamethod

.defmetamethod windows :fresh-line Get the cursor position to the beginning of a blank line. Do this in one of two ways. If the cursor is already at the beginning of a line (that is, at the inside left edge of the window), clear the line to make sure it is blank and leave the cursor where it was. Otherwise, advance the cursor to the next line and clear the line just as if a #\return had been output. The behavior of this operation is not affected by the :cr-not-newline-flag init-option (see (windows-cr-not-newline-flag-init-option)). .end_defmetamethod

.defmetamethod windows :beep &optional beep-type Attempt to attract the user’s attention, by either making a sound with the keyboard or flashing the screen into and out of inverse video or both.

If beep’s value is nil, both are done. If the value is :beep, only the sound is made. If it is :flash, only flashing the screen is done.

No standard meanings have been assigned to beep-type yet. .end_defmetamethod

Function: beep &optional beep-type (stream standard-output) ¶

Beeps by sending a :beep message to stream, passing beep-type as an argument. If the stream does not handle the :beep operation, a sound is made on the keyboard instead.

.defmetamethod windows :display-lozenged-string string Output string in a lozenge. This is how special characters are echoed. .end_defmetamethod

Function: tv:sheet-line-out sheet string start end set-xpos set-ypos dwidth ¶

This is a complicated primitive whose interface is arranged to do exactly what the editor needs for buffer display, to make the editor as fast as possible.

It outputs part of string on sheet like the :fat-string-out operation, but stops if it reaches the right margin (outputting a right margin character if any output remains, if the window calls for that).

If set-xpos and set-ypos are non-nil, the cursor is moved there and a :clear-eol is done, before output starts. If one of these arguments is nil, that dimension of cursor position is not changed. If both are nil, the cursor is not moved and nothing is cleared.

If dwidth is non-nil, it should be a positive number. Output actually starts at index (1- start) in the string, and at x position dwidth less that the cursor position (as found or as set by set-xpos). However, if a :clear-eol is done, it starts at set-xpos. Non-nil dwidth is to be used if the previous character of the string is in an italic font, and is already present on the screen before the output now being done. It causes that character to be output again, presumably overprinting itself, in case a corner of it was erased accidentally because it protrudes to the right of its allocated space.

Returns two values, the final index in the string and the final x cursor position. The window’s cursor is not guaranteed to be moved there; it is undefined on exit from this function. But the value will be correct.

6.3 Output Exceptions ¶

Before doing output to a window, various exceptional conditions are checked for. If an exceptional condition is discovered, a standard operation is invoked to handle it. Redefining or adding daemons to these operations can change the handling of exceptions. For example, output with the cursor too close to the right margin causes an end of line exception; the handling of this exception is what moves the cursor to the next line, or truncates the line, or whatever the window’s flavor arranges for.

The exceptions are actually indicated by flags, bits, set in the window. The operation to handle the exception should do nothing if it is invoked when the corresponding flag is not set, and should not return with the flag still set (or an error will be signaled). The end-of-page and more flags are set and cleared automatically by moving the cursor; as long as things are done properly, they will be set if and only if the cursor is in the right place for them. So the exception handler need only make sure to move the cursor to a good place. The output hold exception handler usually just waits for or brings about a situation in which the reason for the output hold is gone (usually because the window has been exposed).

.defmetamethod windows :handle-exceptions Performs the exception processing described by all the rest of this section. Exceptions are processed in this order:

Output Hold, End-of-Page, **MORE**, and End-of-Line. .end_defmetamethod

• Output Hold and End of Page Exceptions
• **MORE** Exceptions
• End of Line Exceptions

6.4 Cursor Motion ¶

The window’s cursor position is where the upper left corner of the next output character will appear, with a vertical offset if necessary to match up the baselines of various fonts (see (font-baseline)). Recall that cursor position arguments and values of stream operations are relative to the inside upper left corner of the window.

.defmetamethod windows :read-cursorpos &optional (units ':pixel) Return two values: the x and y coordinates of the cursor position. These coordinates are in pixels by default, but if units is :character, the coordinates are given in character-widths and line-heights. (Note that character-widths don’t mean much when you are using variable-width fonts.) .end_defmetamethod

.defmetamethod windows :increment-cursorpos x y &optional (units ':pixel) Advances the cursor position the specified amount in each coordinate. The units may be specified as with :read-cursorpos. This operation is considered to be sequential motion of the cursor through a variable amount of space, rather than instantaneous jumping of the cursor. What this means is that exceptions happen, just as if output were being done. So the cursor wraps around at the margins (or does whatever this window does for :end-of-line-exception and :end-of-page-exception), and **MORE** processing happens at the appropriate place. .end_defmetamethod

The following few operations do cursor motion rather than advancing the cursor. The end-of-page, more and end-of-line exception flags will be set if the cursor is moved to a position where they ought to be on, and can be cleared if they were previously on and the cursor is moved to a place where they ought to be off. Exception handling does not take place.

.defmetamethod windows :set-cursorpos x y &optional (units ':pixel) Moves the cursor position to the specified coordinates. The units may be specified as with :read-cursorpos. If the coordinates are outside the window, move the cursor position to the nearest place to the specified coordinates that is in the window. .end_defmetamethod

.defmetamethod windows :home-cursor Moves the cursor to the upper left corner of the window. .end_defmetamethod

.defmetamethod windows :home-down Moves the cursor to the lower left corner of the window. .end_defmetamethod

.defmetamethod windows :forward-char &optional char Moves the cursor forward one character position, or the width of char in the current font if char is specified. Exceptions are processed, so this is like outputting a space which has the appropriate width. .end_defmetamethod

.defmetamethod windows :backward-char &optional char Moves the cursor backward one character position, or the width of char in the current font if char is specified. Exceptions are processed, but there is no reverse-wraparound. At the left margin, the cursor does not move. .end_defmetamethod

.defmetamethod windows :size-in-characters Returns two values, the dimensions of the window, in units of character-widths and line-heights. (Note that character-widths don’t mean much when you are using variable-width fonts.) .end_defmetamethod

.defmetamethod windows :set-size-in-characters width-spec height-spec &optional option Sets the inside size of the window, according to the two specifications, without changing the position of the upper-left corner. width-spec and height-spec are interpreted the same way as arguments to the :character-width and :character-height init-options, respectively. option is passed along to :set-edges ((windows-set-edges-method)). .end_defmetamethod

6.5 Erasing ¶

All the erasing operations operate on the window pixels by drawing the area to be erased using the window’s erase-aluf as the alu function (see (windows-tv:erase-aluf-instvar)). This is by default tv:alu-andca, which clears the screen bits of the screen area drawn.

.defmetamethod windows :clear-char &optional char Erases the character at the current cursor position. When using variable-width fonts, you tell it the character code of the character you are erasing, so that it will know how wide the character is (it assumes the character is in the current font). If you don’t pass the char argument, it simply erases a character-width, which is fine for fixed-width fonts. .end_defmetamethod

.defmetamethod windows :clear-string string &optional start end Erases enough space, starting at the cursor, to contain string (or the portion of string from start to end), printed in the current font. The entire height of the line is erased, so it does not matter whether the text on the screen is string or something else. string determines only how far to erase. If a fixed-width font is in use, this is equivalent to doing :clear-char once for each character in string. This operation becomes desirable because of variable-width fonts. .end_defmetamethod

.defmetamethod windows :clear-eol Erases from the current cursor position to the end of the current line; that is, erases a rectangle horizontally from the cursor position to the inside right edge of the window, and vertically from the cursor position to one line-height below the cursor position. .end_defmetamethod

.defmetamethod windows :clear-eof Erases from the current cursor position to the bottom of the window. In more detail, first does a :clear-eol, and then clears all of the window past the current line. .end_defmetamethod

.defmetamethod windows :clear-screen Erases the whole window and moves the cursor position to the upper left corner of the window. .end_defmetamethod

.defmetamethod windows :clear-between-cursorposes start-x start-y end-x end-y Erases an area starting at cursor position start-x and start-y, wrapping around if necessary at the end of the line or the page, until end-x and end-y are reached.

Though the arguments are expressed as cursor positions, the cursor position of the window is not changed. .end_defmetamethod

6.6 Inserting and Deleting Lines and Characters ¶

Inserting a character means printing it at the cursor but pushing the rest of the text on the line toward the right margin. Similarly, deleting a character means pulling the following text on the line back toward the left so that the position occupied by the character is closed up. Inserting and deleting lines work the same way vertically, moving the lines below the cursor down or up.

The operations that take a numeric argument specifying the amount of space to insert or delete also take an argument specifying the unit (either :pixel or :character) in which the space has been measured. The unit argument’s meaning is the same as in the :read-cursorpos operation ((windows-read-cursorpos-method)) but the default is :character rather than :pixel.

.defmetamethod windows :delete-char &optional (n 1) (unit ':character) Without an argument, deletes the character at the current cursor position. Otherwise, deletes n characters (or n pixels if unit is :pixel), starting at the cursor position. Move the display of the part of the current line that is to the right of the deleted section leftwards to close the resultant gap. (If unit is :character, this assumes all characters are one character-width wide, and so will not do anything useful with variable-width fonts.) .end_defmetamethod

.defmetamethod windows :delete-string string &optional (start 0) (end nil) This is for deleting specific strings in the current font. It is one of the things to use when dealing with variable-width fonts.

If string is a string, excise a region exactly as wide as that string, or a substring specified by start and end, and moves the display of the part of the current line that is to the right of the excised region leftwards to close the gap.

If string is a number, it is considered to be a character code. The single character is treated like a string containing that character. .end_defmetamethod

.defmetamethod windows :delete-line &optional (n 1) (unit ':character) Without an argument, deletes the line that the cursor is on. Otherwise deletes n lines, or n rows of pixels if unit is :pixel, starting with the one the cursor is on. Moves the display below the deleted section up to close the resulting gap. .end_defmetamethod

.defmetamethod windows :insert-char &optional (n 1) (unit ':character) Opens up a space the width of n characters (or n pixels if unit is :pixel) in the current line at the current cursor position. Shifts the characters to the right of the cursor further to the right to make room. Characters pushed past the right-hand edge of the window are lost. (If unit is :character, this assumes all characters are one character-width wide, and so will not do anything useful with variable-width fonts.) .end_defmetamethod

.defmetamethod windows :insert-string string &optional (start 0) (end nil) (type-too t) Inserts a string at the current cursor position, moving the rest of the line to the right to make room for it.

The string to insert is specified by string; a substring thereof may be specified with start and end, as with :string-out.

string may also be a number, in which case the character with that code is inserted.

If type-too is specified as nil, the string is not actually printed. The space opened up is big enough for the string, but is left blank. .end_defmetamethod

.defmetamethod windows :insert-line &optional (n 1) (unit ':character) Takes the line containing the cursor and all the lines below it, and moves them down one line. The line containing the cursor is moved in its entirety, not broken, no matter where the cursor is on the line. A blank line is created at the cursor. If an argument n is given, opens up n blank lines, or n rows of pixels if unit is :pixel. Lines pushed off the bottom of the window are lost. .end_defmetamethod

6.7 Anticipating the Effect of Output ¶

The following operations do not output, but provide information about what would happen to the cursor and the screen if output were done.

.defmetamethod windows :character-width char &optional (font tv:current-font) Returns the width of the character char, in pixels. The current font is used if font is not specified. If char is a Backspace, :character-width can return a negative number. For Tab, the number returned depends on the current cursor position. If char is Return, the result is defined to be zero. .end_defmetamethod

.defmetamethod windows :compute-motion string &optional (start 0) (end nil) (x tv:cursor-x) (y tv:cursor-y) (cr-at-end-p nil) (stop-x 0) stop-y bottom-limit right-limit font line-height tab-width This is used to figure out where the cursor would end up if you were to output string using :string-out. It does the right thing if you give it just the string as an argument. start and end can be used to specify a substring as with :string-out. x and y can be used to start your imaginary cursor at some point other than the present position of the real cursor. If you specify cr-at-end-p as t, it pretends to do a :line-out instead of a :string-out; a Return is output after the specified portion of the string.

stop-x and stop-y define the size of the imaginary window in which the string is being printed; the printing stops if the cursor becomes simultaneously  both of them. The imaginary printing stops after the character which goes past the stop point. Note that this is not the same as the meaning of the stop-x argument to the :string-length operation! The stop coordinates default to the lower left-hand corner of the window. (This corner is reached before the lower right-hand one, since output goes from left to right on each line.)

bottom-limit and right-limit are vertical and horizontal positions at which to wrap around; they default to the inside height and width of the window. They differ from the stop-x and stop-y in that these act independently when the cursor reaches either one, and they cause the cursor position to change rather than terminating processing.

The computation normally uses font, or the window’s current font if font is nil. However, if string is of type art-fat-string, each character’s %%ch-font field is used as an index in the window’s font map to find the font for that character, and font is ignored except possibly for defaulting the tab-width.

For vertical spacing, line-height is used. The default for line-height is font’s line height if font is non-nil, else the window’s line-height.

tab-width specifies the distance between tab stops, in pixels. If it is omitted, the default is (tv:sheet-tab-width self) if no font is specified, or (* (tv:sheet-tab-nchars self) (tv:font-char-width font)) if a font is specified.

Four values are returned:

• final-x
• final-y The positions at which output stopped.
• final-index nil if the entire imaginary output was completed without reaching or passing the stop point; or the index in string of just after the character that reached or passed the stop point; or t if an implicit Return was requested and it reached or passed the stop point.
• maximum-x The largest x position value reached during processing.

All coordinates for this operation are cursor positions, relative to the window’s inside edges. However, if you specify all the arguments you can use any origin of coordinate system you like, as long as you interpret the values in the same coordinate system. .end_defmetamethod

.defmetamethod windows :string-length string &optional (start 0) (end nil) stop-x (font current-font) (start-x 0) tab-width This is very much like :compute-motion, but works in only one dimension. It tells you how far the cursor would move if string were to be displayed in the current font starting at the left margin, or at start-x if that is specified. start and end work as with :string-out to specify a substring of string. If stop-x is not specified or nil, the window is assumed to have infinite width; otherwise the simulated display will stop before any character which would move the cursor past stop-x pixels from the left edge. If a character exactly reaches stop-x, it can fit. Note that this is not the same as the handling of stop-x in the :compute-motion operation.

The computation normally uses font, or the window’s current font if font is nil. However, if string is of type art-fat-string, each character’s %%ch-font field is used as an index in the window’s font map to find the font for that character, and font is ignored except possibly for defaulting the tab-width.

tab-width specifies the distance between tab stops, in pixels. If it is omitted, the default is (tv:sheet-tab-width self) if no font is specified, or (* (tv:sheet-tab-nchars self) (tv:font-char-width font)) if a font is specified.

:string-length returns three values:

• final-x Where the imaginary cursor ended up.
• final-index The index of the next character in the string (the length of the string if the whole string was processed, or the index of the character which would have moved the cursor past stop-x),
• maximum-x The maximum x coordinate reached by the cursor (this is the same as the first value unless there are Return or Backspace characters in the string).

.end_defmetamethod

6.8 Explicit (Non-Cursor) Output ¶

A window includes some state information which changes as output is done. These include the cursor position, the current font, alu function, and exception flags. The presence of this information makes the window behave coherently as a stream, so that the output from one operation follows that of the previous operation. But sometimes this is not desirable. The "explicit" output operations use a window only for its position and size, with all additional information passed by the caller explicitly. This way, multiple streams of output to the same window can exist, which do not interfere with each other by trying to use a single cursor.

The x and y position arguments used by these operations are relative to the outside edges of the window. This is different from the stream and higher-level operations. It is because these operations are frequently used for drawing parts of the margins, such as labels and margin regions.

.defmetamethod windows :string-out-explicit string start-x start-y x-limit y-limit font alu &optional (start 0) end multi-line-line-height Outputs string (or the portion from start to end) onto the window starting at start-x and start-y, neither using nor moving the window’s cursor position. If x-limit or y-limit is non-nil, output stops if it reaches that position.

Output is done in font using alu function alu. The window’s current font and alu function are not used or set. If there are Return characters in the output, and multi-line-line-height is nil, they are printed as "Return" in a lozenge. If multi-line-line-height is a number, that number is used as the line height, ignoring the window’s line height, and the horizontal output position moves to start-x rather than the left margin for the next line of output.

Note that the arguments of tv:sheet-string-out-explicit are in a different order. The argument order of this operation was cleaned up.

The operation returns three values: the final x position, the final y position, and the final index in the string. You can use these to do multiple operations in consecutive places on the screen. .end_defmetamethod

.defmetamethod windows :string-out-centered-explicit string &optional left y-pos right y-limit font alu (start 0) end multi-line-line-height Outputs string (or the portion from start to end) centered between x positions left and right, at y position y-pos. If y-limit is reached, output stops. left and right default to the inside edges of the window.

Output is done in font and alu, which default to the ones current for the window, and lines are separated by multi-line-line-height (which defaults to the window’s line height). .end_defmetamethod

.defmetamethod windows :string-out-x-y-centered-explicit string &optional left top right bottom font alu start end multi-line-line-height Displays string (or the portion from start to end) with the rectangle it occupies centered both horizontally and vertically. Horizontally it is centered between left and right, and vertically between top and bottom. The defaults for these arguments are the inside edges of the window.

Output is done in font and alu, which default to the ones current for the window, and lines are separated by multi-line-line-height (which defaults to the window’s line height). .end_defmetamethod

6.9 Window Parameters Affecting Output ¶

The following operations and initialization options initialize, get, and set various window attributes which are relevant to the typing out of characters. (See also the operations to manipulate the current font, on (windows-set-current-font-method).)

.defmetainitoption windows :more-p t-or-nil Initializes whether the window should have more processing. It defaults to t. .end_defmetainitoption

.defmetamethod windows :more-p Returns t if more processing (see (more-processing)) is enabled; otherwise, return nil. .end_defmetamethod

.defmetamethod windows :set-more-p more-p If more-p is nil, turns off more processing (see (more-processing)); otherwise turns it on. .end_defmetamethod

.defmetainitoption windows :vsp n-pixels Initializes the window’s vsp. It defaults to 2. .end_defmetainitoption

.defmetamethod windows :vsp Returns the value of vsp for this window (see (vsp)). .end_defmetamethod

.defmetamethod windows :set-vsp new-vsp Sets the value of vsp for this window (see (vsp)) to new-vsp. .end_defmetamethod

.defmetamethod windows :reverse-video-p Returns nil normally or t if the window displays in white on black rather than black on white. This is separate from the whole screen’s inverse video mode, which is what Terminal C sets. .end_defmetamethod

.defmetamethod windows :set-reverse-video-p t-or-nil Enables or disables reverse-video display. Changing this mode inverts all of the bits in the window. .end_defmetamethod

.defmetainitoption windows :reverse-video-p t-or-nil Initializes the use of reverse-video display. .end_defmetainitoption

.defmetainitoption windows :right-margin-character-flag x If x is 1, the window should print an exclamation point in the right margin when :end-of-line-exception happens; if x is 0, it should not. The default is 0. See (right-margin-character-flag-blurb). .end_defmetainitoption

Function: tv:sheet-right-margin-character-flag &optional (window self) ¶

Returns the flag which controls printing of characters at the right margin on wrap-around on window. This is a setf’able accessor macro.

.defmetainitoption windows :backspace-not-overprinting-flag x If x is 0, output of #\backspace will move the cursor position backward; if it is 1, it will display "overstrike" in a lozenge (that is, #\backspace will be just like other special characters). The default is 0. See (backspace-not-overprinting-flag-blurb). .end_defmetainitoption

Function: tv:sheet-backspace-not-overprinting-flag &optional (window self) ¶

Returns the flag which controls how Backspace prints on window. This is a setf’able accessor macro.

.defmetainitoption windows :cr-not-newline-flag x If x is 0, output of #\return will move the cursor position to the beginning of the next line and clear that line; if it is 1, it will display "return" in a lozenge (that is, #\return will be just like other special characters). The default is 0. This flag does not affect the behavior of the :line-out nor the :fresh-line operations. .end_defmetainitoption

Function: tv:sheet-cr-not-newline-flag &optional (window self) ¶

Returns the flag which controls how Return prints on window. This is a setf’able accessor macro.

.defmetainitoption windows :tab-nchars n n is the separation of tab stops on this window, in units of the window’s char-width. This controls how the #\tab character prints. n defaults to 8. .end_defmetainitoption

Function: tv:sheet-tab-nchars &optional (window self) ¶

Returns the distance between tab stops, measured in units of window’s char-width.

Function: tv:sheet-tab-width &optional (window self) ¶

Returns the distance between tab stops, measured in pixels.

7.1 Specifying Fonts ¶

You can control which font is used when output is done to a window. Every window has a font map and a current font. The font map is conceptually an array of fonts; with a small non-negative number, the font map associates a font. The current font of a window is always one of the fonts in the window’s font map. Whenever output is done to a window, the characters are printed in the current font. You can change the font map and the current font of a window at any time with the appropriate operations.

The reason why the window has a font map rather than merely a current font is that it is necessary to know all the fonts that will be used before doing any output in order to know how to position the output properly (so that output in different fonts on the same line will look right).

In addition, certain output operations can accept fat strings (arrays of type art-fat-string) which contain 16-bit characters, and regard the top 8 bits of each character as a font number to look up in the font map. These include :compute-motion, :string-length and :fat-string-out.

.defmetamethod windows :font-map Returns the font map of the window. The object returned is the array that is actually being used to represent the font map inside the window. The elements are actual font objects.

You should not alter anything about this array, since the window depends on it in order to function correctly. To change the font map, use the :set-font-map operation. .end_defmetamethod

.defmetamethod windows :set-font-map new-map Sets the font map to contain the fonts given in new-map. Returns the array of fonts that actually represents the font map inside the window (don’t mess with this array!). new-map may be an array of font specifiers, in which case this array is installed as the new internal array of the window, and the font specifiers are replaced by fonts. Font specifiers are described in the following section; a font or the name of a font may be used.

new-map may also be a list of font specifiers, in which case the array is created from the list in the style of fillarray, with the last element of the list filling in the remaining elements of the array if any (the array is made at least 26. elements long, or long enough to hold all the elements of the list).

If new-map is nil, all the elements of the map are set to the default font of the screen.

The current font is set to zero (the first font in the list or array). The line height and baseline of the window are adjusted appropriately (see below).

The specified font specifiers are remembered so that the :change-of-default-font operation can cause the map to be recomputed from them. This is in case one of the specifiers is a purpose keyword. .end_defmetamethod

.defmetainitoption windows tv:font-map new-map This option lets you initialize the font map. new-map is interpreted the same way it is interpreted by the :set-font-map operation. .end_defmetainitoption

.defmetainstvar windows tv:font-map The window’s font map. .end_defmetainstvar

.defmetamethod windows :current-font Returns the current font, as a font object. .end_defmetamethod

.defmetamethod windows :set-current-font new-font Sets the current font of the window. new-font may be a number, in which case that element of the font map becomes the current font. It may also be a font specifier, in which case the font that the specifier describes is used, unless that font is not in the font map, in which case an error is signalled. Only fonts already in the font map may be selected. .end_defmetamethod

.defmetainstvar windows tv:current-font The window’s current font. .end_defmetainstvar

.defmetamethod windows :baseline Returns the maximum baseline of all the fonts in the font map. The bases of all characters will be aligned so as to be this many pixels below the y cursor position, which is top of the line on which the characters are printed. In other words, when a character is drawn, it will be drawn below the cursor position, by an amount equal to the difference between this number and the baseline of the font of the character. .end_defmetamethod

.defmetainstvar windows tv:baseline The position of the baseline of a text line, in pixels from the top of the line’s vertical extent (its cursor position). .end_defmetainstvar

Function: tv:sheet-font-map window ¶

Function: tv:sheet-baseline window ¶

Function: tv:sheet-current-font window ¶

Accessor defsubsts for the corresponding instance variables.

You can use the List Fonts command in Zmacs to get a list of all of the fonts that are currently loaded into the Lisp environment. Here is a list of some of the useful fonts:

• fonts:cptfont This is the default font, used for almost everything.
• fonts:medfnt This is the default font in menus. It it a fixed-width font with characters somewhat larger than those of cptfont.
• fonts:medfnb This is a bold version of medfnt. When you use Split Screen, for example, the Do It and Abort items are in this font.
• fonts:hl12i This is a variable-width italic font. It is useful for italic items in menus; ZMail uses it for this in several menus.
• fonts:tr10i This is a very small italic font. It is the one used by the inspector to say "More above" and "More below".
• fonts:hl10 This is a very small font used for non-selected items in Choose Variable Values windows.
• fonts:hl10b This is a bold version of hl10, used for selected items in Choose Variable Values windows.

• Font Specifiers

7.2 Attributes of Fonts ¶

Fonts, and characters in fonts, have several interesting attributes. One attribute of each font is its character height. This is a non-negative fixnum used to figure out how tall to make the lines in a window. We have mentioned earlier that each window has a certain line height. The line height is computed by examining each font in the font map, and finding the one with the largest character height. This largest character height is added to the vsp specified for the window (see (vsp)), and the sum is the line height of the window. The line height, therefore, is recomputed every time the font map is changed or the vsp is set. It works this way so that there will always be enough room on any line for the largest character of the largest font to be displayed, and still leave the specified vertical spacing between lines. One effect of this is that if you have a window that has two fonts, one large and one small, and you do output in only the small font, the lines will still be spaced far enough apart that characters from the large font will fit. This is because the window system can’t predict when you might, in the middle of a line, suddenly switch to the large font.

Another attribute of a font is its baseline. The baseline is a non-negative fixnum that is the number of raster lines between the top of each character and the base of the character. (The "base" is usually the lowest point in the character, except for letters that descend below the baseline such as lower case "p" and "g".) This number is stored so that when you are using several different fonts side-by-side, they will be aligned at their bases rather than at their tops or bottoms. So when you output a character at a certain cursor position, the window system first examines the baseline of the current font, then draws the character in a position adjusted vertically to make the bases of all the characters line up.

There is another attribute called the character width. This can be an attribute either of the font as a whole, or of each character separately. If there is a character width for the whole font, it is as if each character had that character width separately. The character width is the amount by which the cursor position should be moved to the right when a character is output on the window. This can be different for different characters if the font is a variable-width font, in which a "W" might be much wider than an "i". Note that the character width does not necessarily have anything to do with the actual width of the bits of the character (although it usually does); it is just defined to be the amount by which the cursor should be moved.

There is another attribute that is an attribute of each character separately; it is called the left kern. Usually it is zero, but it can also be a positive or negative fixnum. When the window system draws a character at a given cursor position, and the left kern is non-zero, then the character is drawn to the left of the cursor position by the amount of the left kern, instead of being drawn exactly at the cursor position. In other words, the cursor position is adjusted to the left by the amount of the left kern of a character when that character is drawn, but only temporarily; the left kern affects only where the single character is drawn and does not have any cumulative effect on the cursor position.

A font that does not have separate character widths for each character and does not have any non-zero left kerns is called a fixed-width font. The characters are all the same width and so they line up in columns, as in typewritten text. Other fonts are called variable-width because different characters have different widths and things do not line up in columns. Fixed-width fonts are typically used for programs, where columnar indentation is used, while variable-width fonts are typically used for English text, because they tend to be easier to read and to take less space on the screen.

Each font also has attributes called the blinker width and blinker height. These are two non-negative fixnums that tell the window system a nice-looking width and height to make a rectangular blinker for characters in this font. These attributes are completely independent of everything else and are used only for making blinkers. Using a fixed width blinker for a variable-width font is not the nicest-looking thing to do; instead, the editor actually re-adjusts its blinker width as a function of what character it is on top of, making a wide blinker for wide characters and a narrow blinker for narrow characters. But if you don’t want to go to this trouble, or don’t necessarily know just which character the blinker is on top of, you can just use the font’s blinker width as the width of your blinker. For a fixed-width font there’s no problem.

There is also an array for each font called the char-exists table. It is an art-1b array with a 1 for each character that actually exists in the font, and a 0 for other characters. This table is not used by the character-drawing software; it is just for informational purposes. Characters that do not exist have pictures with no bits "on" in them, just like the "space" character. Most fonts implement most of the printing characters in the character set, but some are missing some characters.

7.3 Format of Fonts ¶

This section explains the internal format in which fonts are represented. Most users do not need to know anything about this format; you can skip this section without loss of continuity.

Fonts are represented as arrays. The body of the array holds the bits of the characters, and the array leader holds the attributes of the font and characters as well as information about the format of the body of the array. Note that there is only one big array holding all the characters, rather than a separate array for each character. The format in which the bits are stored is specially designed to maximize the speed of character drawing and to minimize the size of the data structure, and so it is not as simple you might expect.

FED operates on fonts by converting them into a different type of object containing the same data. This new object is called a font descriptor; it is simpler and easier to work with. See the files SYS: IO1; FNTDEF LISP for the format of font descriptors, and SYS: IO1; FNTCNV LISP for functions to operate on them, and to convert between font descriptors and fonts.

The font format works slightly differently depending on whether the font contains any characters that are wider than thirty-two bits. If there are any such characters, then the font is considered to be "wide", and a single character may be made up of several subcharacters to be drawn side by side. A wide font stores subcharacters instead of characters as such, and has a table indicating which subcharacters belong to each character of the character set. For the time being, we will discuss only narrow fonts in which there is no need to distinguish characters from subcharacters because each character is made of a single subcharacter.

Each character in a font has an array of bits stored for it. The dimensions of this array are called the raster width and raster height. The raster width and raster height are the same for every character of a font; they are properties of the font as a whole, not of each character separately. Consecutive rows are stored in the array; the number of rows per character is the raster height, and the number of bits per row is the raster width. An integral number of rows are stored in each word of the array; if there are any bits left over, those bits are unused. Thus no row is ever split over a word boundary. Rows are stored right-adjusted, from right to left. When there are more rows than will fit into a word, the next word is used; remaining bits at the left of the first word are ignored, and the next row is stored right-adjusted in the next word, and so on. An integral number of words is used for each character.

For example, consider a font in which the widest character is seven bits wide and the tallest character is six bits tall. The raster width of the font is seven and the raster height is six. Each row of a character is seven bits, and so four of them fit into a thirty-two bit word, with four bits wasted. The remaining two rows require a second word, the rest of which will be unused because the number of words per character must be an integer. So this font will have four rows per word, and two words per character. To find the bits for character three of the font, you multiply the character number, three, by the number of words per character, two, and find that the bits for character three start in word six. The rightmost seven bits of word six are the first row of the character, the next seven bits are the second row, and so on. The rightmost seven bits of the seventh word are the fifth row, and the next seven bits of the seventh word are the sixth and last row.

Note that we have been talking about "words" of the array. The character-drawing microcode does not actually care what type the array is; it only looks at machine words as a whole, unlike most of the array-referencing in the Lisp Machine. In a Lisp-object-holding array such as an art-q array, the leftmost eight bits are not under control of the user, and so these kinds of arrays are not suitable for fonts. In general, you need to be able to control the contents of every bit in the array, and so usually fonts are art-1b arrays. This means you need to know the internal storage layout of bits within an art-1b array in order to fully understand the font format, so here it is: the zeroth element of an art-1b array is the rightmost bit of the zeroth word, and successive elements are stored from right to left in that word. The thirty-third element is the rightmost bit in the next word, and so on.

Now, if there are any characters in the font that are wider than 32 bits, then even a single row of the font will not fit into a word. Such characters are divided into subcharacters no more than 32 bits wide, and the character is drawn by drawing all its subcharacters, one by one, side by side. The character drawing microcode can only handle ordinary narrow characters, and it is invoked once for each subcharacter in order to draw a wide character. In order to make this work, the wide font stores subcharacters in the same way a narrow font stores its characters.

In addition, the wide font has a font indexing table which gives the first subcharacter number for each character code. (In a narrow font, the font indexing table is nil.) The character W would be drawn by finding the value at index 127 (the code for W) in the font indexing table, and the value at index 130. Suppose that these are 171 and 173. Then W is made up of subcharacters 171 and 172. Either of these subcharacters’ bits can be found in the same way that the bits for character code 171 or 172 would be found in a narrow font.

The array leader of a font is a structure defined by defstruct. Here are the names of the accessors for the elements of the array leader of a font.

Function: tv:font-name font ¶

The name of the font. This is a symbol whose value is the font and which serves to name the font. The print-name of this symbol appears in the printed representation of the font.

Function: tv:font-char-height font ¶

The character height of the font; a non-negative fixnum.

Function: tv:font-char-width font ¶

The character width of the characters of the font; a non-negative fixnum. If the tv:font-char-width-table of this font is non-nil, then this element is ignored except that it is used to compute the distance between horizontal tab stops; it is typically the width of a lower-case "m".

Function: tv:font-baseline font ¶

The baseline of this font; a non-negative fixnum.

Function: tv:font-char-width-table font ¶

If this is nil then all the characters of the font have the same width, and that width is given by the tv:font-char-width of the font. Otherwise, this is an art-q array of non-negative fixnums, one for each logical character of the font, giving the character width for that character. The array must be an art-q array for the sake of the sys:%string-translate function.

Function: tv:font-left-kern-table font ¶

If this is nil then all characters of the font have zero left kern. Otherwise, this is an array of fixnums, one for each logical character of the font, giving the left kern for that character.

Function: tv:font-blinker-width font ¶

The blinker width of the font.

Function: tv:font-blinker-height font ¶

The blinker height of the font.

Function: tv:font-chars-exist-table font ¶

This is an art-1b array with one element for each logical character of the file. The element is 1 if the character exists and 0 if the character does not exist.

Function: tv:font-raster-height font ¶

The raster height of the font; a positive fixnum.

Function: tv:font-raster-width font ¶

The raster width of the font; a positive fixnum.

Function: tv:font-rasters-per-word font ¶

The number of rows of a character stored in each word of the font; a positive fixnum.

Function: tv:font-words-per-char font ¶

The number of words stored for each character or subcharacter; a positive fixnum.

Function: tv:font-indexing-table font ¶

If this is nil, then no characters of this font are wider than thirty-two bits. Otherwise, this is the font indexing table of the font, an array indexed by character code, containing the number of the first subcharacter for that character code. There is an extra array element at an index one greater than the largest character code; it says where the subcharacters of the largest character code stop.

7.4 Color Fonts ¶

We mentioned earlier that you need to use different fonts to draw on different kinds of screen. To draw on a color screen, you must use a color font. If you just pass in a font specifier when you specify an element of a font map, then a color version of that font will be created if there isn’t one already, and it will be used as the font.

A color font is almost the same as a regular black-and-white font except that for each pixel there are many bits. For example, for a four-bit color display (the only type presently supported), there are four bits for each pixel. While nothing prevents each pixel of a font from having any value it wants, usually each pixel is either zero or one other specific value; that is, color fonts do not usually have multicolored characters in them, or two characters of different color.

Color fonts can be created from black-and-white fonts by the following function:

Function: color:make-color-font bw-font &optional (color 17) (suffix "") ¶

Creates and returns a new font. bw-font should be an existing black-and-white font. The new font has all the same attributes as bw-font, and each character has the same attributes as the corresponding character in bw-font. For each zero-valued pixel in bw-font, the pixel in the new font is zero as well. For each one-valued pixel in bw-font, the pixel in the new font has value color. The name of the new font is formed by appending "color-", the print-name of the name of bw-font, and suffix together to form a string, and then interning that string in the fonts package.

When a font specifier is examined and the window system decides to make a color version of the font, it calls color:make-color-font with only one argument, letting the others default. So, for example, if a color version of fonts:foo-font is automatically created, its name will be fonts:color-foo-font, and its pixels will have the value 17 wherever those in the original font have the value one. However, you can call color:make-color-font to make many color versions of the same black-and-white font, each in a different color.

Something to keep in mind when using color fonts is that when characters of a color font are drawn, onto a color window, and the char-aluf of the window is tv:alu-ior (as it normally is), then the bits of the pixels of the character will be bit-wise "or"’ed with the existing bits in the pixels of the window. If the existing bits (that is, the background against which the character is being drawn) are all zero, there’s no problem. But if they are not, the resulting values of the pixels will be some color determined by a bit-wise "or" of two color values, which is unlikely to yield meaningful results. Unless this is actually what you want, you should make sure that the background is made of zeroes before drawing characters onto a color window.

8.1 Alu Functions ¶

Most graphics operations take an alu argument, which controls how the bits of the graphic object being drawn are combined with the bits already present in the window. In most cases this argument is optional and defaults to the window’s char-aluf (see (char-aluf)), the same alu function as is used to draw characters, which is normally inclusive-or. The following variables have the most useful alu functions as their values:

Variable: tv:alu-ior ¶

Inclusive-or alu function. Bits in the object being drawn are turned on and other bits are left alone. This is the char-aluf of most windows. If you draw several things with this alu function, they will write on top of each other, just as if you had used a pen on paper.

Variable: tv:alu-andca ¶

And-with-complement alu function. Bits in the object being drawn are turned off and other bits are left alone. This is the erase-aluf of most windows. It is useful for erasing areas of the window or for erasing particular characters or graphics.

Variable: tv:alu-xor ¶

Exclusive-or alu function. Bits in the object being drawn are complemented and other bits are left alone. Many graphics programs use this. The graphics operations take quite a bit of care to do "the right thing" when an exclusive-or alu function is used, drawing each point exactly once and including or excluding boundary points so that adjacent objects fit together nicely. The useful thing about exclusive-or is that if you draw the same thing twice with this alu function, the window’s contents are left just as they were when you started; so this is good for drawing objects if you want to erase them afterwards.

Variable: tv:alu-seta ¶

Alu function to copy the input bits into the output bits, ignoring the old values of the output bits. This is not useful with the drawing operations, because the exact size and shape of the affected region depend on the implementation details of the microcode. The seta function is useful with the bitblt operations, where it causes the source rectangle to be transferred to the destination rectangle with no dependency on the previous contents of the destination.

Variable: tv:alu-and ¶

"And" alu function. Like tv:alu-seta, this is not useful with the drawing operations, but can be useful with the bitblt operations. 1 bits in the input leave the corresponding output bit alone, and 0 bits in the input clear the corresponding output bit.

8.2 Flavor Operations for Graphics ¶

.defmethod tv:graphics-mixin :point x y Returns the numerical value of the picture element at the specified coordinates. The result is 0 or 1 on a black-and-white TV. Clipping is performed; if the coordinates are outside the window, the result will be 0. .end_defmethod

.defmethod tv:graphics-mixin :draw-point x y &optional alu value Draws value into the picture element at the specified coordinates, combining it with the previous contents according to the specified alu function (value is the first argument to the operation, and the previous contents is the second argument.) value should be 0 or 1 on a black-and-white TV. Clipping is performed; that is, this operation will have no effect if the coordinates are outside the window. value defaults to -1, which is a pixel with all bits 1. .end_defmethod

.defmethod tv:stream-mixin :bitblt alu width height from-array from-x from-y to-x to-y Copies a rectangle of bits from from-array onto the window. The rectangle has dimensions width by height, and its upper left corner has coordinates (from-x,from-y). It is transferred onto the window so that its upper left corner will have coordinates (to-x,to-y). The bits of the transferred rectangle are combined with the bits on the display according to the Boolean function specified by alu. As in the bitblt function, if from-array is too small it is automatically replicated.

See the discussion of the bitblt function ((bitblt-fun)) for complete details. Note that to-array is constrained as described there. See also the tv:make-sheet-bit-array function below ((tv:make-sheet-bit-array-fun)). .end_defmethod

.defmethod tv:stream-mixin :bitblt-from-sheet alu width height from-x from-y to-array to-x to-y Copies a rectangle of bits from the window to to-array. All the other arguments have the same significance as in :bitblt.

See the discussion of the bitblt function ((bitblt-fun)) for complete details. Note that to-array is constrained as described there. See also the tv:make-sheet-bit-array function below ((tv:make-sheet-bit-array-fun)). .end_defmethod

.defmethod tv:stream-mixin :bitblt-within-sheet alu width height from-x from-y to-x to-y Copies a rectangle of bits from the window to some other place in the window. All the other arguments have the same significance as in :bitblt. Note that width or height may be negative, in which case the coordinates to be copied extend to lower values from the specified starting values, and copying is done in reverse order. The order bits are copied makes no difference when copying between different arrays but is important when copying between overlapping portions of one array. .end_defmethod

.defmethod tv:graphics-mixin :draw-char font char x y &optional alu Displays the character with code char from font font on the window with its upper left corner at coordinates (x,y). This lets you draw characters in any font (not just the ones in the font map), and it lets you put them at any position without affecting the cursor position of the window. .end_defmethod

.defmethod tv:graphics-mixin :draw-line x1 y1 x2 y2 &optional alu (draw-end-point t) Draws a line on the window with endpoints (x1,y1) and (x2,y2). If draw-end-point is specified as nil, does not draw the last endpoint (that is, stops drawing just before that point instead of at it). This is useful with alu function tv:alu-xor when multiple connected lines are in use, since drawing an endpoint once each for two lines would cancel out. .end_defmethod

.defmethod tv:graphics-mixin :draw-lines alu x0 y0 x1 y1 ... xn yn Draws n lines on the screen, the first with endpoints (x0,y0) and (x1,y1), the second with endpoints (x1,y1) and (x2,y2), and so on. The points between lines are drawn exactly once and the last endpoint, at (xn,yn), is not drawn. .end_defmethod

.defmethod tv:graphics-mixin :draw-dashed-line x0 y0 x1 y1 alu dash-spacing space-literally-p offset dash-length Draws a line divided into dashes. The first five arguments are the same as those of the :draw-line operation.

The argument dash-spacing specifies the period of repetition of the dashes; it is the length of a dash plus the length of a space between dashes. Its default value is 20. dash-length is the length of the actual dash; it defaults to half the spacing.

If space-literally-p is nil, the spacing between dashes is adjusted so that the dashes fit evenly into the length of line to be drawn. If it is non-nil, the spacing is used exactly as specified, even though that might put the end point in the middle of a space between dashes.

A nonzero offset is used if you want a space between the starting point and the beginning of the first dash. The value is the amount of space desired, in pixels. The same space will be provided at the end point, if space-literally-p is nil. offset defaults to zero. .end_defmethod

.defmethod tv:graphics-mixin :draw-curve x-array y-array &optional end alu closed-p Draws a sequence of connected line segments. The x and y coordinates of the points at the ends of the segments are in the arrays x-array and y-array. The points between line segments are drawn exactly once and the point at the end of the last line is not drawn at all; this is especially useful when alu is tv:alu-xor. The number of line segments drawn is 1 less than the length of the arrays, unless a nil is found in one of the arrays first in which case the lines stop being drawn. If end is specified it is used in place of the actual length of the arrays.

If closed-p is non-nil, the end point is connected back to the first point. .end_defmethod

.defmethod tv:graphics-mixin :draw-wide-curve x-array y-array width &optional end alu closed-p Like :draw-curve but width is how wide to make the lines. .end_defmethod

.defmethod tv:stream-mixin :draw-rectangle width height x y &optional alu Draws a filled-in rectangle with dimensions width by height on the window with its upper left corner at coordinates (x,y). .end_defmethod

.defmethod tv:graphics-mixin :draw-triangle x1 y1 x2 y2 x3 y3 &optional alu Draws a filled-in triangle with its corners at (x1,y1), (x2,y2), and (x3,y3). .end_defmethod

.defmethod tv:graphics-mixin :draw-circle center-x center-y radius &optional alu Draws the outline of a circle centered at the point center-x, center-y and of radius radius. .end_defmethod

.defmethod tv:graphics-mixin :draw-circular-arc center-x center-y radius start-theta end-theta &optional alu Draws part of the outline of a circle centered at the point center-x, center-y and of radius radius.

The part of the circle to be drawn is specified by start-theta and end-theta. These angles are in radians; an angle of zero is the positive x direction, and angles increase counter-clockwise. The arc starts at start-theta and goes through increasing angles, passing through zero if necessary, to stop at end-theta. .end_defmethod

.defmethod tv:graphics-mixin :draw-filled-in-circle center-x center-y radius &optional alu Draws a filled-in circle specified by its center and radius. .end_defmethod

.defmethod tv:graphics-mixin :draw-filled-in-sector center-x center-y radius theta-1 theta-2 &optional alu Draws a "triangular" section of a filled-in circle, bounded by an arc of the circle and the two radii at theta-1 and theta-2. These angles are in radians; an angle of zero is the positive-X direction, and angles increase counter-clockwise. .end_defmethod

.defmethod tv:graphics-mixin :draw-regular-polygon x1 y1 x2 y2 n &optional alu Draws a filled-in, closed, convex, regular polygon of (abs n) sides, where the line from (x1,y1) to (x2,y2) is one of the sides. If n is positive then the interior of the polygon is on the right-hand side of the edge (that is, if you were walking from (x1,y1) to (x2,y2), you would see the interior of the polygon on your right-hand side; this does not mean "toward the right-hand edge of the window"). .end_defmethod

.defmethod tv:graphics-mixin :draw-cubic-spline px py z &optional curve-width alu c1 c2 p1-prime-x p1-prime-y pn-prime-x pn-prime-y Draws a cubic spline curve that passes through a sequence of points. The arrays px and py hold the x and y coordinates of the sequence of points; the number of points is determined from the active length of px. Through each successive pair of points, a parametric cubic curve is drawn with the :draw-curve operation, using z points for each such curve. If curve-width is provided, the :draw-wide-curve operation is used instead, with the given width. The cubics are computed so that they match in position and first derivative at each of the points. At the end points, there are no derivatives to be matched, so the caller must specify the boundary conditions. c1 is the boundary condition for the starting point, and it defaults to :relaxed; c2 is the boundary condition for the ending point, and it defaults to the value of c1. The possible values of boundary conditions are:

• :relaxed Makes the derivative zero at this end.
• :clamped Allows the caller to specify the derivative. The arguments p1-prime-x and p1-prime-y specify the derivative at the starting point, and are only used if c1 is :clamped; likewise, pn-prime-x and pn-prime-y specify the derivative at the ending point, and are only used if c2 is :clamped.
• :cyclic Makes the derivative at the starting point and the ending point be equal. If c1 is :cyclic then c2 is ignored. To draw a closed curve through n points, in addition to using :cyclic, you must pass in px and py with one more than n entries, since you must pass in the first point twice, once at the beginning and once at the end.
• :anticyclic Makes the derivative at the starting point be the negative of the derivative at the ending point. If c1 is :anticyclic then c2 is ignored.

.end_defmethod

Function: tv:spline px py z &optional cx cy c1 c2 p1-prime-x p1-prime-y pn-prime-x pn-prime-y ¶

This subroutine of the :draw-cubic-spline operation is also useful in its own right. It does the computation of the spline to be drawn, then converts it into a sequence of line segments, returning arrays of x and y coordinates of endpoints of lines. :draw-cubic-spline works by passing these arrays to the :draw-curve operation.

The function returns three values, an array of x coordinates, an array of y coordinates, and the number of active points in those arrays. (The arrays are not required to have fill pointers.)

The arrays to be used can be supplied as the cx and cy arguments, or else new arrays will be created. If arrays are supplied and too short, they will be made longer.

8.3 Low-Level Graphics Using Subprimitives ¶

Drawing graphics on a window is usually done by sending messages to the window. However, there is a certain overhead in sending each message. If your application requires speed, you can go to some more trouble by writing your very own method to do graphics. It is a good idea not to do this until you know that using existing messages will not work; it is easier and less bug-prone to use the existing messages than to write handlers for new ones.

To write a new method you must have a flavor to which to attach that method. In this case, we want to add some graphics messages to existing kinds of windows. So, what we want here is a mixin flavor. You will define a new mixin flavor for your application. You will add methods to this flavor to do the things you need to do. Then, when you want to create an actual window to use, you will create a window of a new flavor; this new flavor will include, as one of its mixins, your new mixin. For a simple case, you might use the following flavor definitions:

(defflavor circus-mixin () ()
   (:required-flavors tv:essential-window))
   ;;This makes the instance variables of tv:essential-window accessible.

(defmethod (circus-mixin :draw-clown) (size weight happy-p)
  ...)

(defmethod (circus-mixin :draw-tent) 
           (height &optional (number-of-rings 3))
  ...)

(defflavor circus-window () (circus-mixin tv:window))

Now you can instantiate windows of flavor circus-window, and they will support your new messages.

Within the definition of a primitive output operation you will use the graphics subprimitives such as sys:%draw-char rather than the high-level operations described in previous sections. To avoid errors, you should use these subprimitives only from within window methods that provide the error checking that the subprimitives lack.

In addition, the subprimitives must be used only within the body of a tv:prepare-sheet special form. An error is signaled if they are used elsewhere.

Special Form: tv:prepare-sheet body... ¶

Executes body in an environment in which it is safe to draw on the window. tv:prepare-sheet waits until the window is not output-held or locked, and then opens all blinkers that could be on top of the window so that they will not interfere with the output (see (open-blinkers)). It also turns off interrupts so that the window will remain unlocked and the blinkers will remain open.

Because interrupts are turned off, you must be careful in writing the body. It should execute for no longer than you would mind being unable to do a Control-Abort. It also must not wait for anything, since that would allow the blinkers to reappear and defeat the whole purpose of preparing the sheet.

The microcode subprimitives generally use coordinates relative to the outside edges of the window. This is unlike the high-level interfaces, which use cursor positions, in which the margins of the window do not count. Also, subprimitives do little or no clipping or other testing for coordinates that are out of bounds. The results of passing erroneous coordinates are unpredictable; in principle, the machine might halt.

Another place you can use the subprimitives is inside the :blink operation of a blinker. This operation is always invoked in a suitable environment for calling them, including interrupts off. Because blinkers are always drawn by xor’ing, it does not actually matter whether any other blinkers are present.

These instance variables and macros are useful in writing output primitives:

• (tv:sheet-inside-left)
• (tv:sheet-inside-right) Return the positions of the inside left edge and the inside right edge, both relative to the outside left edge. If your operation is intended to output on the inside of the window, these may be useful for clipping, and also for converting cursor positions to low-level coordinates.
• (tv:sheet-inside-top)
• (tv:sheet-inside-bottom) Return the positions of the inside top edge and the inside bottom edge, both relative to the outside top edge.
• (tv:sheet-inside-width)
• (tv:sheet-inside-height) Return the inside size of the window.
• tv:width
• tv:height The total width and height of the window, including the margins.
• tv:cursor-x
• tv:cursor-y The current cursor position, expressed in outside coordinates. That is to say, these values are not "cursor positions" in the usual sense of that term, but they do describe the position of the cursor.
• tv:screen-array The array of bits that hold the contents of the window. Usually this is an indirect array that points to part of the screen, although it may also point to the superior’s bit-save array, as described in (exposure). You can use ar-2-reverse and as-2-reverse on this array, indexed by coordinates relative to the outside edges, to examine and draw individual points. The dimensions of this array will be the width and height.
• tv:char-aluf
• tv:erase-aluf These are the alu function codes (see (alu-functions)) that are supposed to be used for normal drawing and erasing. :tyo, :string-out and so on all use tv:char-aluf and all the standard erase operations use tv:erase-aluf. If your operation is a kind of drawing or a kind of erasing, it may be correct for you to use one of these two.

  Usually tv:char-aluf is tv:alu-ior, which means to turn on (set to all ones) the corresponding bits in the array. tv:erase-aluf is usually tv:alu-andca, which means to turn off (set to zero) the relevant bits. However, they would be different if the window were in reverse video mode. Reverse video mode is not a highly-used feature, but by using these variables you can make your extensions work correctly in reverse video mode, so it is cleaner to use them.

  However, you may use any alu function. tv:alu-xor is often useful. tv:alu-seta is usually not wise to use, since it will often result in the alteration of bits that you did not expect to change, but which happen to fall in the same word as the ones you were working on.

• tv:current-font This is the window’s current font. If you are drawing characters, it is usually correct to use this font.

Here is an example from the tv:graphics-mixin flavor, changed by adding the tv: prefixes in the places where you would need them if you were to write this outside the tv package.

(defmethod (graphics-mixin :draw-point)
	   (x y &optional (alu tv:char-aluf) (value -1))
  (tv:prepare-sheet (self)
    (setq x (+ x (tv:sheet-inside-left))
	  y (+ y (tv:sheet-inside-top)))
    (if (not (or (< x (tv:sheet-inside-left))
		 ( x (tv:sheet-inside-right))
		 (< y (tv:sheet-inside-top))
		 ( y (tv:sheet-inside-bottom))))
	(setf (ar-2-reverse tv:screen-array x y)
	      (boole alu value 
		     (ar-2-reverse tv:screen-array x y))))))

This method takes its arguments in inside coordinates, and so it first converts them to outside coordinates. Then it compares them with the boundaries of the inside of the window, and does nothing if they are outside those boundaries. This is how it does clipping. Finally, if everything is OK, it reads out the current value of the point, combines it with the new value using the specified alu function (which defaults to the char-aluf of the window), and stores it back into the array.

• Subprimitives for Drawing

9.1 Blinker Functions and Operations ¶

Function: tv:make-blinker window &optional (flavor 'tv:rectangular-blinker) &rest options ¶

Creates and returns a new blinker. The new blinker is associated with the given window, and is of the given flavor. Other useful flavors of blinker are documented below. The options are initialization-options to the blinker flavor. All blinkers include the tv:blinker flavor, and so init-options taken by tv:blinker will work for any flavor of blinker. Other init-options may only work for particular flavors.

.definstvar tv:blinker tv:x-pos .definstvar1 tv:blinker tv:y-pos The current position of the blinker on its window, or nil if the blinker should follow the window’s cursor. .end_definstvar

.definitoption tv:blinker :x-pos x .definitoption1 tv:blinker :y-pos y Set the initial position of the blinker within the window. These init-options are irrelevant for blinkers that follow the cursor. The initial position for non-following blinkers defaults to the current cursor position. .end_definitoption

.defmethod tv:blinker :read-cursorpos Returns two values: the x and y components of the position of the blinker within the inside of the window. .end_defmethod

.defmethod tv:blinker :set-cursorpos x y Sets the position of the blinker, relative to the inside of the window. If the blinker has been a following blinker (that is, one which follows the window’s cursor) then it ceases to be one, and from this point on moves only when :set-cursorpos is done. .end_defmethod

.defmethod tv:blinker :size Returns the width and height of the blinker area occupied by the blinker, in pixels, as two values. Each flavor of blinker implements this differently. .end_defmethod

.defmethod tv:blinker :set-size new-width new-height Sets the size of the blinker’s displayed pattern. Not all blinker flavors actually do anything, but they will all allow the operation. For example, character blinkers have no way to change their size because there is no mechanism for automatically scaling fonts. .end_defmethod

.definitoption tv:blinker :follow-p t-or-nil Sets whether the blinker follows the cursor; if this option is non-nil, it does. By default, this is nil, and so the blinker’s position gets set explicitly. .end_definitoption

.defmethod tv:blinker :set-follow-p new-follow-p Sets whether the blinker follows the cursor. If this is nil, the blinker stops following the cursor and stays where it is until explicitly moved. Otherwise, the blinker starts following the cursor. .end_defmethod

.definstvar tv:blinker tv:visibility The blinker’s current visibility. .end_definstvar

.defmethod tv:blinker :visibility .defmethod1 tv:blinker :set-visibility new-visibility Get or set the visibility of the blinker. The specified visibility should be one of :on, nil, :off, t, or :blink; their meanings are described above. .end_defmethod

.definitoption tv:blinker :visibility visibility Initializes the visibility. .end_definitoption

.definstvar tv:blinker tv:deselected-visibility The blinker’s deselected visibility. .end_definstvar

.definitoption tv:blinker :deselected-visibility symbol Sets the initial deselected visibility. By default, it is :on. .end_definitoption

.defmethod tv:blinker :deselected-visibility .defmethod1 tv:blinker :set-deselected-visibility new-visibility Examine or change the deselected visibility of the blinker. .end_defmethod

.definstvar tv:blinker tv:half-period The time interval in 60ths of a second between successive blinks of the blinker. This is relevant only if the visibility is :blink. .end_definstvar

.defmethod tv:blinker :half-period .defmethod1 tv:blinker :set-half-period new-half-period Get or set the half-period of the blinker. The argument is in 60ths of a second. .end_defmethod

.definitoption tv:blinker :half-period half-period Initialize the half-period. The default is 15. .end_definitoption

.definstvar tv:blinker tv:sheet The window or screen this blinker moves on. .end_definstvar

.defmethod tv:blinker :sheet Gets the window or screen that the blinker moves on. .end_defmethod

.defmethod tv:blinker :set-sheet new-sheet Sets to new-sheet the window or screen on which the blinker moves. If the old window is an ancestor or descendant of new-sheet, adjusts the (relative) position of the blinker so that it does not move. Otherwise, moves it to the point (0,0). .end_defmethod

.definstvar tv:blinker tv:time-until-blink The time interval in 60ths until the next time this blinker should blink. For a blinking blinker, this controls the next turning on or off.

A non-blinking blinker will not necessarily change its state at the specified time, but it will be checked at that time and displayed if it is supposed to be visible but is not. This is how blinkers reappear after being opened so that output can be done. .end_definstvar

.defmethod tv:blinker :defer-reappearance This operation is invoked whenever a blinker is opened in order to prepare a sheet, if the visibility is not :blink and if the blinker is scheduled to reappear in less than 25/60 sec. By default, it is defined to delay the blinker’s reappearance until 1/2 sec after the present. .end_defmethod

.definstvar tv:blinker tv:phase t when the blinker is present on the screen, nil when it is not. .end_definstvar

.defmethod tv:blinker :phase Returns t if the blinker is now displayed on the screen. .end_defmethod

.defmetamethod blinkers :blink Draws or erases the blinker. Since the blinker is always drawn by xor’ing, drawing it and erasing it are usually exactly the same. The method can examine the instance variable tv:phase to tell which one is happening, but usually there is no need to know. The :blink operation may assume that the blinker’s sheet is prepared for output. It is always called with interrupts disabled. .end_defmetamethod

Special Form: tv:with-blinker-ready do-not-open body... ¶

This macro is useful in writing methods of blinkers that change the size, position, shape or anything else that affects how the blinker appears. It executes body after preparing to remove the blinker self from the screen. If do-not-open is nil, the blinker is actually opened before body is executed. Otherwise, body may call tv:open-blinker if it wants the blinker open. Interrupts are disabled by this macro in any case, so that if the blinker is opened it remains open for the duration of body.

Once the blinker is opened, its instance variables may be set without special care.

Function: tv:open-blinker blinker ¶

Clears blinker off from the screen if it is currently drawn. This does not change blinker’s visibility. Blinkers that are supposed to be visible but are not on the screen are put back on the screen by the scheduler, every so often. Thus, a blinker can be relied on to stay open only as long as interrupts are disabled.

Function: tv:sheet-following-blinker window ¶

Returns a blinker that follows window’s cursor, or nil if that window has no such blinker. If there is more than one, it returns the first one it finds (it is pretty useless to have more than one, anyway).

Function: tv:turn-off-sheet-blinkers window ¶

Sets the visibility of all blinkers on window to :off.

9.2 Blinker Flavors ¶

All the flavors in this section depend on tv:blinker.

For other blinker flavors and related considerations for use of a blinker for mouse tracking, see the section on mouse blinkers, (mouse-blinkers).

.defflavor tv:rectangular-blinker This is one of the flavors of blinker provided for your use. A rectangular blinker is displayed as a solid rectangle; this is the kind of blinker you see in Lisp listeners and editor windows. The width and height of the rectangle can be controlled. .end_defflavor

.definitoption tv:rectangular-blinker :width n-pixels .definitoption1 tv:rectangular-blinker :height n-pixels Set the initial width and height of the blinker, in pixels. By default, they are set to the font-blinker-height and font-blinker-width (see (tv:font-blinker-height-fun)) of the zeroth font of the window associated with the blinker. .end_definitoption

.defmethod tv:rectangular-blinker :set-size new-width new-height Sets the width and height of the blinker, in pixels. .end_defmethod

.defmethod tv:rectangular-blinker :set-size-and-cursorpos new-width new-height x y Sets the width and height of the blinker, in pixels, and also its position, at once. This avoids any chance that the blinker will appear on the screen with its old size and new position, or vice versa. .end_defmethod

.defflavor tv:hollow-rectangular-blinker (tv:rectangular-blinker) This flavor of blinker displays as a hollow rectangle; the editor uses such blinkers to show you which character the mouse is pointing at. This flavor includes tv:rectangular-blinker, and so all of tv:rectangular-blinker’s init-options and operations work on this too. .end_defflavor

.defflavor tv:box-blinker (tv:rectangular-blinker) This flavor of blinker is like tv:hollow-rectangular-blinker except that it draws a box two pixels thick, whereas the tv:hollow-rectangular-blinker draws a box one pixel thick. This flavor includes tv:rectangular-blinker, and so all of tv:rectangular-blinker’s init-options and operations work on this too. .end_defflavor

.defflavor tv:stay-inside-blinker-mixin This mixin makes a rectangular blinker, or any modified version thereof, keep all of its corners inside the blinker’s sheet. Normally a blinker only makes sure that its position (its upper left corner) is within the sheet. Trying to position this sort of blinker in a bad place positions it against the edge of the sheet, as near as possible to the requested place. .end_defflavor

.defflavor tv:ibeam-blinker This flavor of blinker displays as an I-beam (like a capital I). Its height is controllable. The lines are two pixels wide, and the two horizontal lines are nine pixels wide. .end_defflavor

.definitoption tv:ibeam-blinker :height n-pixels Sets the initial height of the blinker. It defaults to the line-height (see (char-width-and-line-height)) of the window. .end_definitoption

.defflavor tv:character-blinker This flavor of blinker draws itself as a character from a font. You can control which font and which character within the font it uses. .end_defflavor

.definitoption tv:character-blinker :font font Sets the font in which to find the character to display. This may be anything acceptable to the :parse-font-specifier operation (see (tv:screen-parse-font-specifier-method)) of the window’s screen. You must provide this. .end_definitoption

.definitoption tv:character-blinker :character ch Sets the character of the font to display. You must provide this. .end_definitoption

.defmethod tv:character-blinker :character Returns the character that this blinker is displaying as. .end_defmethod

.defmethod tv:character-blinker :set-character new-character &optional new-font Sets the character to be displayed to new-character. Also, if new-font is provided, set the font to new-font. new-font may be anything acceptable to the :parse-font-specifier operation (see (tv:screen-parse-font-specifier-method)) of the window’s screen. .end_defmethod

.definstvar tv:character-blinker tv:character .definstvar1 tv:character-blinker tv:font The character being displayed, and the font it is displayed in. .end_definstvar

.defflavor tv:bitblt-blinker (tv:mouse-blinker-mixin) A blinker that displays by copying a two-dimensional array of pixels onto the screen. The array’s size must be at least the blinker’s size. As it happens, this flavor also includes the ability to be the mouse blinker. .end_defflavor

.definitoption tv:bitblt-blinker :array array This option specifies the array of pixels to be used to display the blinker. Use make-pixel-array to create the array. If you do not specify this option, you must specify both the :height and :width options, which will be used to create an array. .end_definitoption

.definitoption tv:bitblt-blinker :width n-pixels .definitoption1 tv:bitblt-blinker :height n-pixels Set the initial width and height of the blinker, in pixels. .end_definitoption

.defmethod tv:bitblt-blinker :size Returns the width and height of the blinker. If this is less than the size of the blinker’s array, then only part of the array, starting at the upper left corner, is used. .end_defmethod

.defmethod tv:bitblt-blinker :set-size width height Sets the size of the blinker, making a new array if the old one is not as big as the new size. .end_defmethod

.defmethod tv:bitblt-blinker :array .defmethod1 tv:bitblt-blinker :set-array array Get or set the array of pixels to be used to display the blinker. .end_defmethod

.definstvar tv:bitblt-blinker tv:array .definstvar1 tv:bitblt-blinker tv:height .definstvar1 tv:bitblt-blinker tv:width These instance variables hold the special information of bitblt blinkers. .end_definstvar

.defflavor tv:magnifying-blinker (tv:bitblt-blinker) A kind of bitblt blinker which automatically displays a "magnified" version of some of the dots underneath it. A small square of screen pixels is magnified by replacing each pixel with an n by n square of identical pixels, where n is the blinker’s magnification factor.

The x-offset and y-offset which the blinker has by virtue of tv:mouse-blinker-mixin (see (tv:mouse-blinker-mixin-flavor)) help determine the center of magnification. The position of the magnifying blinker is, as always, the position of its upper left corner. However, the cursor positions plus the offsets give the point which the blinker is indicating (this is the place where the mouse position would be, if this blinker were the mouse blinker). The magnification is done so as to keep that point on the screen fixed. .end_defflavor

.definitoption tv:magnifying-blinker :magnification factor Specifies the magnification factor of the magnifying blinker. 3 is a good value to use. The height and width of the blinker should be multiples of the magnification. So should the offsets. .end_definitoption

.defmethod tv:magnifying-blinker :magnification .defmethod1 tv:magnifying-blinker :set-magnification factor Get or set the magnification factor of the blinker. .end_defmethod

.definstvar tv:magnifying-blinker tv:magnification The magnification factor of the blinker. .end_definstvar

.defflavor tv:reverse-character-blinker (tv:bitblt-blinker) This flavor of blinker appears as a solid rectangle with a character removed from it. That is, a solid rectangle and the character are both drawn, and xor with each other. This flavor of blinker proved to be very confusing in the use for which it was originally implemented, but there seems no point in deleting it entirely.

All the operations and init options of tv:character-blinker are provided, though this flavor does not depend on that one.

The position of the blinker is at the upper left corner of the rectangle. The position of the upper left corner of the character with respect to the rectangle is specified with the init options :character-x-offset and :character-y-offset. .end_defflavor

.definitoption tv:reverse-character-blinker :character-x-offset n-pixels .definitoption1 tv:reverse-character-blinker :character-y-offset n-pixels Specify the offset of the character’s upper left corner to the right and down from the blinker position (the rectangle’s upper left corner). .end_definitoption

10.1 Encoding Mouse Clicks as Characters ¶

Clicks on the mouse are sometimes encoded into characters. Such characters are normally forced into input buffers of windows (see (tv:stream-mixin-force-kbd-input-method)), and so they are distinguished from regular keyboard characters by having the %%kbd-mouse bit turned on. Encoding of clicks is done with tv:mouse-button-encode (see (tv:mouse-button-encode-fun)). See (characters) for full information the fields of such a character.

Note that "mouse clicks" can also be done on the keyboard. See the variables tv:use-kbd-buttons and tv:*mouse-incrementing-keystates*, in (mouse-parameters).

These standard mixins handle mouse clicks by forcing keyboard input describing the click:

.defflavor tv:kbd-mouse-buttons-mixin Handles mouse clicks by encoding them as characters which are forced into the window’s input buffer. In more detail: if it is a double-click on the right button, the system menu is called forth. Otherwise, the encoded character representation of the click is forced into the input buffer of the window. Furthermore, if it is a single-click on the left button, the window is selected.

The state of the Control, Meta, Super and Hyper keys at the time of the click is included in the character, in the %%kbd-control, etc., fields (see (%%kbd-control-var)). .end_defflavor

.defflavor tv:list-mouse-buttons-mixin This is just like tv:kbd-mouse-buttons-mixin except that a blip goes in the input buffer rather than just an encoded click. The blip looks like:

  (:mouse-button encoded-click window x y)

This is more useful than just the encoded click: it tells you where the mouse was (relative to the outside part of the window), and which window the mouse was over (this is useful primarily if several windows are sharing the same input buffer).

The state of the Control, Meta, Super and Hyper keys is included in the encoded click, in the %%kbd-control, etc., fields. .end_defflavor

The following subtle point may explain some difficulties you may have with the above flavors. It is a tricky point, and you can ignore it if you don’t understand it. The characters (or blips) created by the flavors above go straight into the window’s input buffer. Under some circumstances they may bypass pending characters that have been typed ahead at the keyboard. So if you type something and then mouse-click at something in rapid succession while your program is busy, the program may see the mouse-click before it sees the character from the keyboard. [This may be fixed in the future.] See (typeahead-explanation), for further discussion of these issues.

10.2 Ownership of the Mouse ¶

Usually the mouse is handled according to the window that it is positioned over. We say that this window owns the mouse. The window that owns the mouse is the one that will receive the :handle-mouse, :mouse-moves and :mouse-click messages. So the usual case is that the window under the mouse owns the mouse.

Since windows are arranged in a hierarchy, generally a window, its superior, its superior’s superior, and so on, are all under the mouse at the same time. So the window that owns the mouse is really the lowest window in the hierarchy (farthest in the hierarchy from the screen) that is visible (it and all its ancestors are exposed). If you move the window to part of the screen occupied by a partially-visible window, then one of its ancestors (often the screen itself) becomes the owner. The screen handles single-clicking on the left button by selecting the window under it; this is why you can select partially-visible windows with the mouse.

A greedy window can keep ownership of the mouse even if the mouse moves outside of it, by setting tv:window-owning-mouse to that window. This should be done only when that window has come by the mouse by legitimate means, inside a :handle-mouse operation on that window or one of the other operations invoked by it. Inferiors of the greedy window can still own the mouse when it is over them. Greediness ends when tv:window-owning-mouse is set back to nil (its normal state). Then the mouse goes back to being owned by whichever window is under it. While a window is being greedy, mouse tracking continues to use the methods of the owning window, but the way of determining the owning window is changed.

The mouse can also be grabbed, which means that some process has taken it away from all windows. This state is represented by tv:window-owning-mouse being t. See (grabbing-mouse).

Usurping the mouse is an even more drastic method of taking over control. It turns the mouse process off, so you have to do the tracking yourself. See (usurping-mouse).

Variable: tv:window-owning-mouse ¶

If this is nil, the mouse is owned by the window under it. If this is t, the mouse is grabbed. If this is a window, the mouse is owned by that window.

Function: tv:window-owning-mouse ¶

Returns the window that now owns the mouse, either because it is being greedy or because the mouse is over it. If the mouse has been grabbed, the value is t.

Variable: tv:mouse-window ¶

The window that is currently handling the mouse. This is the window that tv:window-owning-mouse returned the last time the mouse process called it.

Function: tv:mouse-wakeup ¶

Informs the mouse process that the screen layout has changed. Anything which may change which window is under any point where the mouse might be should call this function.

.defflavor tv:hysteretic-window-mixin This mixin makes a window continue to own the mouse (by being greedy) for a small distance beyond the edges of the window. This distance is called the hysteresis, and you can specify it. This mixin is used by momentary menus, so that if you accidentally slip a bit outside the menu, the menu won’t vanish; you have to get well away from it before it vanishes. .end_defflavor

.definitoption tv:hysteretic-window-mixin :hysteresis n-pixels Sets the initial value of the hysteresis, in pixels. It defaults to 25. (decimal). .end_definitoption

.defmethod tv:hysteretic-window-mixin :hysteresis .defmethod1 tv:hysteretic-window-mixin :set-hysteresis new-hysteresis Examine or set the hysteresis of the window. .end_defmethod

• Grabbing the Mouse
• Usurping the Mouse

10.3 How Windows Handle the Mouse ¶

The mouse is rarely grabbed or usurped. Normally it is owned by a window (or a screen). Then, mouse handling works through various flavor operations on the owning window. There are several operations, used at various points in mouse handling, to give you convenient hooks for modifying a window’s behavior.

The outermost loop of mouse handling determines the owning window and then invokes its :handle-mouse method. When this method returns, the owning window is recalculated.

.defmetamethod windows :handle-mouse This operation is invoked by the mouse process to handle the mouse while it is on this window. It should return only when the mouse moves out of the window, or if the mouse is grabbed.

The default definition is to call tv:mouse-standard-blinker followed by tv:mouse-default-handler. .end_defmetamethod

Function: tv:mouse-default-handler window scroll-bar-p ¶

The guts of the :handle-mouse operation. :handle-mouse methods typically set up the desired sort of mouse blinker and then call this function. window is the window the mouse is being handled for, and scroll-bar-p is t to provide a scroll bar (see (scroll-bar)), if the window implements one. Generally the :enable-scrolling-p operation is used to compute the second argument.

A second argument of :in is used for handling the scroll bar itself. Values other than nil, t and :in should be avoided.

This function invokes the :mouse-moves operation to inform the window about mouse motion, and the :mouse-buttons operation to inform it about buttons going down. They are the most convenient hooks to use for implementing simple new mouse behaviors.

.defmetamethod windows :set-mouse-cursorpos x y .defmetamethod1 windows :set-mouse-position x y Move the mouse instantaneously to the specified position. The effect is as if the user had moved the mouse over to that spot, without the user actually touching it. For :set-mouse-position, x and y are relative to the outside edges of the window. For :set-mouse-cursorpos, they are relative to the inside edges (as in the :set-cursorpos operation). .end_defmetamethod

.defmetamethod windows :mouse-moves x y This operation is invoked in the mouse process every time the mouse moves either into, within or out of this window. x and y are the current position of the mouse, relative to the outside edges of this window.

:mouse-moves handlers should always call tv:mouse-set-blinker-cursorpos to make the mouse blinker move. In addition, they frequently move other blinkers or turn them on or off. This is how menus arrange to outline the item the mouse is over.

tv:mouse-default-handler is what invokes this operation.

When this window ceases to own the mouse, for whatever reason, the :mouse-moves method will always be called one final time, so that it can turn off extra blinkers, etc. .end_defmetamethod

Function: tv:mouse-set-blinker-cursorpos &rest ignore ¶

Moves the current mouse blinker to the current mouse position. :mouse-moves methods typically call this function.

.defmetamethod windows :mouse-buttons mask x y This operation is invoked in the mouse process when a button is pressed. mask is a mask of the buttons pressed, and x and y are the mouse position (in the mouse sheet).

By default, this calls tv:mouse-button-encode to check for double clicks, then brings up the system menu for double-click-right; otherwise, it invokes the :mouse-click operation.

tv:mouse-default-handler is what invokes this operation. .end_defmetamethod

.defmetamethod windows :mouse-click mouse-char x y This operation is where most handling of mouse clicks actually goes on. It is invoked in the mouse process. mouse-char is a character code describing the button pressed and how many times; such as, #\mouse-l-2. x and y are the position of the mouse at the beginning of the click. It is preferable to use this position rather than the current one, because the user positioned the mouse accurately before clicking and motion during the click was probably accidental.

Any window selection desired should be done in another process, using process-run-function or tv:mouse-select. It is unrobust to do something so error-prone in the mouse process.

:or method combination is used, so that all the methods are run until one of them returns non-nil. So each mixin can define a way of handling the mouse under certain circumstances, and it can decline to handle the click by returning nil. For example, tv:margin-choice-mixin defines a :mouse-click method which handles the click if the position is inside a margin choice box, and returns nil otherwise so that the window’s primary way of handling clicks can be run.

tv:kbd-mouse-buttons-mixin and tv:list-mouse-buttons-mixin work by defining :mouse-click methods. .end_defmetamethod

.defmetamethod windows :who-line-documentation-string This operation should return a string describing what the mouse would do if clicked on this window in its current position. For example, menus return a string describing the menu item that the mouse is over. If different buttons do different things, or if multiple clicks are in use, the string should describe all the possibilities. .end_defmetamethod

Function: tv:mouse-select window ¶

Selects window, and safe to use in the mouse process because it creates a temporary process to do the work in that case. Used by :mouse-click methods.

Function: tv:mouse-call-system-menu ¶

Brings up the system menu, and designed to be safe to use in the mouse process. Used by :mouse-click methods.

10.4 Mouse Blinkers ¶

At any time one blinker is the mouse blinker, which follows the motion of the mouse. It is not always the same blinker. Each window can set up the kind of mouse blinker it wants or change the blinker, as long as that window owns the mouse.

The mouse blinker’s sheet is the mouse sheet, not the window that owns the mouse and wants this blinker to be used. This avoids problems with displaying the blinker at points near the edge of the owning window which require parts of the blinker to be outside that window.

Note that mouse blinkers are not following blinkers; the mouse cursor position is independent of the cursor position of the owning window and also independent of the cursor position of the mouse sheet.

The recommended way to make a window flavor use a special form of mouse cursor is to give the flavor a :mouse-standard-blinker method which alters the mouse blinker using tv:mouse-set-blinker or tv:mouse-set-blinker-definition (see below).

Usually there is only one form of mouse blinker used for any given window. If you want the mouse blinker’s appearance to vary while the mouse remains in the same window, a good technique is to have the :mouse-standard-blinker method know how to set up whichever blinker appearance is right at the moment it is called, and then call tv:mouse-standard-blinker after every event that might necessitate changing the blinker.

Variable: tv:mouse-blinker ¶

The blinker now following the mouse. It should not be changed by the user directly.

Function: tv:mouse-set-blinker blinker &optional x-offset y-offset ¶

Makes blinker the new mouse blinker. If x-offset and y-offset are non-nil, blinker’s offsets (see below) are also set.

blinker can be a defined blinker type instead of a blinker. Then this function is equivalent to tv:mouse-set-blinker-definition with only three arguments specified ((tv:mouse-set-blinker-definition-fun)).

This function is typically called from :mouse-standard-blinker methods.

Function: tv:mouse-standard-blinker &optional (window (tv:window-owning-mouse)) ¶

Sets the mouse blinker to the standard kind for window, by invoking the :mouse-standard-blinker operation on it. This is called by the window system at appropriate times.

.defmetamethod windows :mouse-standard-blinker This should use tv:mouse-set-blinker or tv:mouse-set-blinker-definition to set up the right kind of mouse blinker to use when the mouse is on this window. By default, it is defined to pass on the message to the superior window; finally, the screen handles the operation by making the blinker an upward-left arrow. .end_defmetamethod

.defflavor tv:mouse-blinker-mixin Not all blinkers can serve as mouse blinkers. This mixin makes a blinker suitable for use as the mouse blinker.

A mouse blinker has two offsets which relate the blinker position to the mouse position. Remember that the blinker position is where the upper left corner of the blinker is displayed. The upper left corner is not always what you want to place at the precise spot the mouse is pointing to. For example, if you are using a character blinker with the character X, probably the center of the X rather than its corner should be "the spot". .end_defflavor

.defmethod tv:mouse-blinker-mixin :offsets Returns the x and y offsets of the blinker as two values. The values give the position of the mouse cursor relative to the blinker; that is, in order to locate the cursor within the area of the blinker’s display, the offsets must be positive. .end_defmethod

.defmethod tv:mouse-blinker-mixin :set-offsets x y Sets the offsets of the blinker. .end_defmethod

.defflavor tv:mouse-character-blinker .defflavor1 tv:mouse-rectangular-blinker .defflavor1 tv:mouse-hollow-rectangular-blinker .defflavor1 tv:mouse-box-blinker .defflavor1 tv:mouse-box-stay-inside-blinker These are versions of popular blinker flavors described in (blinker-flavors), which can be used as the mouse blinker. tv:mouse-box-stay-inside-blinker incorporates tv:stay-inside-blinker-mixin. .end_defflavor

The flavors tv:bitblt-blinker and tv:magnifying-blinker are already suited to be mouse blinkers.

• Reusable Mouse Blinker Types

10.5 Mouse Scrolling ¶

Some windows have the ability to scroll. They display only a portion of a virtual window which is (or may be) too big to be shown all at once. Scrolling means moving the actually-shown portion up or down through the entire display.

• Scrolling Protocol
• Scroll Bars
• Margin Scrolling

((top-height top-left top-right)
 (bottom-height bottom-left bottom-right))

(keyword at-end-message more-message font-specifier)

10.6 Mouse Parameters ¶

Variable: tv:use-kbd-buttons ¶

If this is non-nil, the Roman numeral keys I through III on the keyboard are treated as mouse clicks when the Mode-Lock key is down. The default is t.

Variable: tv:mouse-bounce-time ¶

The delay in microseconds after a change in a mouse button status before the system begins to look for another change. The default is 2000. microseconds.

Variable: tv:mouse-double-click-time ¶

The delay in microseconds after which the system gives up checking for an additional mouse click. The default is .2 seconds.

Function: tv:mouse-discard-clickahead ¶

Clears out the microcode buffer in which the mouse-tracking microcode records mouse clicks.

Variable: tv:*mouse-incrementing-keystates* ¶

This is a list of keys (valid arguments for tv:key-state). When the mouse is clicked, each of these keys that is held down adds one to the "number of clicks". The default value is

(:control :shift :hyper)

Thus, if you do a single click with the Control key down, it is treated as a double click.

11.1 Borders ¶

.defflavor tv:borders-mixin The tv:borders-mixin margin item creates the borders around windows that you often see when using the Lisp Machine. You can control the thickness of each of the four borders separately, or of all of them together. You can also specify your own function to draw the borders, if you want something more elaborate than simple lines.

The borders also include some whitespace left between the borders and the inside of the window. The thickness of this white space is called the border margin width. The space is there so that characters and graphics that are up against the edge of the inside of the window, or the next-innermost margin item, do not "merge" with the border. .end_defflavor

.definitoption tv:borders-mixin :borders argument This option initializes the parameters of the borders. argument may have any of the following values:

• nil There are no borders at all.
• a symbol or a number A specification (see below) that applies to each of the four borders.
• a list (left top right bottom) Specifications (see below) for each of the borders at the four edges of the window.
• a list (keyword1 spec1 keyword2 spec2...) Specifications (see below) for the borders at the edges selected by the keywords, which may be among :left, :top, :right, :bottom.

Each specification for a particular border may be one of the following. It specifies how thick the border is and the function to draw it.

• nil This edge should not have any border.
• t The border at this edge should be drawn by the default function with the default thickness.
• a number The border at this edge should be drawn by the default function with the specified thickness.
• a symbol The border at this edge should be drawn by the specified function with the default thickness for that function.
• a cons (function . thickness) The border at this edge should be drawn by the specified function with the specified thickness.

The default (and currently only) border function is tv:draw-rectangular-border. Its default width is 1.

To define your own border function, you should create a Lisp function that takes six arguments: the window on which to draw the label, the "alu function" (see (aluf)) with which to draw it, and the left, top, right, and bottom edges of the area that the border should occupy. The returned value is ignored. The function runs inside a tv:sheet-force-access (see (tv:sheet-force-access-fun)). You should place a tv:default-border-size property on the name of the function, whose value is the default thickness of the border; it will be used when a specification is a non-nil symbol.

Note that setting border specifications to ask for a border width of zero is not the same thing as giving nil as the argument to this option, because in the former case the space for the border margin width (see the previous page) is allocated, whereas in the latter case it is not. .end_definitoption

.defmethod tv:borders-mixin :set-borders new-borders Redefines the borders. new-borders can be any of the things that can be used for the :borders init option (see above). .end_defmethod

.definitoption tv:borders-mixin :border-margin-width n-pixels Sets the width of the white space in the margins between the borders and the inside of the window. The default is 1. If some edge does not have any border (the specification for that border was nil) then that border won’t have any border margin either, regardless of the value of this option; that is the difference between border specifications of 0 and nil. .end_definitoption

.defmethod tv:borders-mixin :border-margin-width .defmethod1 tv:borders-mixin :set-border-margin-width new-width Return or set the value of the border margin width. .end_defmethod

.definstvar tv:borders-mixin tv:border-margin-width The current border margin width. .end_definstvar

.definstvar tv:borders-mixin tv:borders A description of the currently specified borders. It is nil for no borders. Otherwise its format is complicated and internal in nature. .end_definstvar

.defflavor tv:full-screen-hack-mixin This mixin is included in many system flavors, such as Lisp listeners, Supdup, and Zmacs frames. It offers the user the option of requesting that these windows have no borders when they occupy the full screen. .end_defflavor

Function: tv:flush-full-screen-borders flush-p ¶

With an argument of t, eliminates the borders of all windows which are full-screen-sized and have tv:full-screen-hack-mixin.

With an argument of nil, reinstates the normal borders of all such windows.

11.2 Labels ¶

.defflavor tv:label-mixin The tv:label-mixin margin item creates the labels in the corners of windows that you often see when using the Lisp Machine. You can control the text of the label, the font in which it is displayed, and whether it appears at the top of the window or the bottom. .end_defflavor

.defmetainitoption windows :name The value is the name of the window, which should be a symbol. All windows have names; note that this is an init option of tv:minimum-window. It is mentioned here because the main use of the name is as the default string for the label, if there is a label (see below). .end_defmetainitoption

.defmetamethod windows :name Returns the name of the window, which is a symbol. See above. .end_defmetamethod

.definitoption tv:label-mixin :label specification Sets the string displayed as the label, the font in which the label is displayed, and whether the label is at the top or the bottom of the window. Anything you don’t specify will default; by default, the string is the same as the name of the window, the font is the screen’s standard font for the purpose :label (see (font-purposes)), and the label is at the bottom of the window.

specification may be any of:

• nil There is no label at all.
• t The label is given all the default characteristics.
• :top The label is put at the top of the window.
• :bottom The label is put at the bottom of the window.
• a string The text displayed in the label is this string.
• a font The label is displayed in the specified font.
• a list (keyword1 arg1 keyword2 ...) The attributes corresponding to the keywords are set; the rest of the attributes default. Some keywords take arguments and some do not. The following keywords may be given:
  • :top The label is put at the top of the window.
  • :bottom The label is put at the bottom of the window.
  • :centered The label is printed horizontally centered, rather than starting at the left edge.
  • :string string The text displayed in the label is string.
  • :font font-specifier The label is displayed in the specified font. font-specifier may be any font specifier (see (font-specifier)).
  • :vsp vsp If the label is multiple lines, lines will be separated by vsp rows of pixels.

.end_definitoption

.defmethod tv:label-mixin :label-size Returns the width and height of the area occupied by the label. .end_defmethod

.defmethod tv:label-mixin :set-label specification Changes some attributes of the label. specification can be anything accepted by the :label init option. Any attribute that specification doesn’t mention retains its old value. .end_defmethod

.definstvar tv:label-mixin tv:label The value of this variable describes the label of the window. It is either nil for no label or a list of length eight, whose elements are

• tv:label-left
• tv:label-top
• tv:label-right
• tv:label-bottom The rectangle allocated to the label. All four edges are relative to the window’s outside upper left corner.
• tv:label-font The font to use for the label.
• tv:label-string The string to display in the label.
• tv:label-vsp The separation between lines in the label.
• tv:label-centered Non-nil if the label text should be horizontally centered.

.end_definstvar

.defflavor tv:top-label-mixin Causes the label to appear in the top margin of the window by default instead of at the bottom. The mixin does not override an explicit specification of the label position. .end_defflavor

.defflavor tv:box-label-mixin Makes the label appear to be in a box, by drawing a line just on the inside of the label. This combines with the window’s borders, which surround the other three sides of the label, to make a box. The extra line is present only if the label is turned on. Menus use this mixin, so from any menu that has a label, such as the one you get from Split Screen in the system menu, you can see what it looks like. .end_defflavor

.definitoption tv:box-label-mixin :label-box-p t-or-nil If this option is nil, the box around the label is inhibited. .end_definitoption

.defflavor tv:centered-label-mixin Makes the label string appear by default horizontally centered in the width of the window. .end_defflavor

.defflavor tv:delayed-redisplay-label-mixin This flavor adds the :delayed-set-label and :update-label operations to your window. You send a :delayed-set-label message to change the label in such a way that it will not actually be displayed until you send an :update-label message. This is especially useful for programs that suppress redisplay when there is typeahead; the user’s commands may change the label several times, and you may want to suppress the redisplay of the changes in the label until there isn’t any typeahead. .end_defflavor

.defmethod tv:delayed-redisplay-label-mixin :delayed-set-label specification This is like the :set-label method, except that nothing actually happens until an :update-label is done. .end_defmethod

.defmethod tv:delayed-redisplay-label-mixin :update-label Actually does the :set-label operation on the specification given by the most recent :delayed-set-label operation. .end_defmethod

.definstvar tv:delayed-redisplay-label-mixin tv:label-needs-updating Non-nil if a :delayed-set-label has been done but not displayed yet. .end_definstvar

11.3 Margin Regions ¶

Margin regions are a general facility for allocating space in a window’s margin for specific purposes. Each region can display text or graphics and can be mouse sensitive. Margin choices (see (margin-choice)) are implemented using margin regions.

.defflavor tv:margin-region-mixin This mixin gives a window the ability to have margin regions. .end_defflavor

.definstvar tv:margin-region-mixin tv:region-list A list of margin region descriptors. Each descriptor specifies one margin region and is a list of this form:

(function margin size left top right bottom)

The list may be longer than seven. The meaning of the extra elements is up to you. Here is what the seven standard elements mean. We list the names of the defsubsts provided to access them.

• tv:margin-region-function A function to handle various operations on the margin region. It is called with an operation name as the first argument, so it could be a flavor instance, but no flavors are predefined for the purpose and usually the function is a defselect. The margin region descriptor itself is always one of the arguments, to identify the region being operated on.
• tv:margin-region-margin The name of the margin that this region lives in; either :left, :top, :right or :bottom.
• tv:margin-region-size The thickness in pixels of the margin region, perpendicular to the edge it is next to. (The other dimension is controlled by the size of the window, possibly diminished by space already reserved for other margin items.)
• tv:margin-region-left
• tv:margin-region-top
• tv:margin-region-right
• tv:margin-region-bottom The edges of the rectangle assigned to the margin region. If positive, they are relative to the outside upper left corner of the window. If negative, they are relative to the outside lower right corner.

  You do not specify these; they are computed by the :redefine-margins operation which divides up the margin space, and recorded here so that the margin region can be displayed and found by the mouse.

The margin region descriptor may be longer than seven. Additional elements are not used by tv:margin-region-mixin itself and therefore may be used by higher-level facilities to record their own information with each margin region. .end_definstvar

.defmethod tv:margin-region-mixin :set-region-list new-region-list Sets the list of margin regions. The new list should be a list of margin region descriptors as described above, but only the first three elements of each descriptor need be filled in. The rest will be set up automatically. .end_defmethod

These are the operations that the function of a margin region is expected to handle:

• :refresh descriptor This operation should draw this region on the screen in the position specified by the margin region descriptor.
• :mouse-enters-region descriptor This operation is invoked whenever the mouse moves into this region.
• :mouse-leaves-region descriptor This operation is invoked whenever the mouse moves out of this region.
• :mouse-moves x y descriptor This operation is invoked when the mouse moves within a region. It is also invoked, following the :mouse-enters-region operation, when the mouse moves into a region. x and y are the new mouse position, relative to the outside of the window.
• :mouse-click x y descriptor mouse-char This operation is invoked when the mouse is clicked on this region, except for double click right. If the operation does nothing, the mouse click has no effect. The argument mouse-char is like that of the :mouse-click window operation ((windows-mouse-click-method)).
• :who-line-documentation-string descriptor This operation is invoked to get who line documentation to be used when the mouse is in this region. It should return a string describing the meaning of mouse clicks on the region.

Function: tv:margin-region-area descriptor ¶

Returns the four edges of the rectangle allocated to descriptor’s margin region, all relative to the window’s outside upper left corner. This may only be used inside of methods of the window whose margin region is being operated on.

• Margin Region Example

(declare-flavor-instance-variables (tv:margin-scroll-mixin)
(defselect margin-scroll-region
  (:refresh (region &optional old-valid
		    &aux more-p left top right bottom)
   (multiple-value (left top right bottom)
     (tv:margin-region-area region))
   ;; Is there anything more to scroll to past this edge?
   (setq more-p 
	 (send self
	       (if (eq (tv:margin-region-margin region) ':top)
		   ':scroll-more-above ':scroll-more-below)))
   ;; Redisplay string in the region unless already right.
   (when (or (not old-valid) 
	     (neq more-p (margin-scroll-region-more-p region)))
     (setf (margin-scroll-region-more-p region) more-p)
     (tv:sheet-force-access (self)
       ;; Erase the region.  Sheet has just been prepared.
       (tv:%draw-rectangle (- right left) (- bottom top)
			   left top tv:erase-aluf self)
       ;; Print the string.
       (send self ':string-out-centered-explicit
	     (if more-p (margin-scroll-region-more-msg region)
	       (margin-scroll-region-empty-msg region))
	     left top right nil
	     (margin-scroll-region-msg-font region) tv:char-aluf
	     0 nil nil))))

  ((:mouse-enters-region :mouse-leaves-region :mouse-moves)
   (&rest ignore))
  (:mouse-click (ignore ignore region ignore)
   (if (margin-scroll-region-more-p region)
       (let ((from (tv:margin-region-margin region)))
	 (send self ':scroll-relative
	       from (if (eq from ':top) ':bottom ':top)))
       (beep)))
  (:who-line-documentation-string (ignore)
    "Any button to scroll one page.")))

11.4 Defining Margin Item Flavors ¶

Let us assume that you want to define a thing called a mumble that goes in a window’s margins, the way labels and borders do. You create a flavor mumble-margin-mixin that implements the feature.

This flavor should have certain instance variables, which will be used only by the methods of mumble-margin-mixin so their precise format is up to you.

• current-mumbles Some sort of specification of what mumbles this window should have. It might record text to display for the mumbles, a font to use, etc.
• mumble-margin-area Records the rectangle within the window where the mumbles should go. Everything that deals with the location of the mumbles on the screen should act based on the value of this variable.

  It is recommended to use a list of four values: the left, top, right and bottom edges of the rectangle, all relative to the upper left outside corner of the window.

Some margin mixins have just a single variable whose value is a list containing both the contents and the position of the margin item.

Example:

(defflavor mumble-margin-mixin 
	   ((current-mumbles nil) mumble-margin-area)
	   ()
  (:required-flavors tv:minimum-window)
  (:inittable-instance-variables current-mumbles))

(defmethod (mumble-margin-mixin :before :init) (ignore)
  (setq current-mumbles 
	(canonicalize-and-validate-mumble-spec 
	  current-mumbles)))

Now you must at the minimum create methods for two standard operations for margin computation and display, to interface mumble-margin-mixin to the rest of the system. These operations are :compute-margins and :refresh-margins.

.defmetamethod windows :compute-margins lm tm rm bm :compute-margins is used by the system to find out how much space is needed in each margin of the window by borders, labels, and anything else. Each flavor that implements a kind of margin item must define a method for it. This operation uses :pass-on method combination, so that the values from one method become the arguments to the next. These arguments are interpreted as the amount of space allocated so far in each margin. Each method increments one or more of them by the amount of space needed by that mixin. .end_defmetamethod

.defmetamethod windows :refresh-margins Redraws all the contents of the window’s margins. Each flavor of margin item must add a daemon method to this operation. The method may assume that its own margin area is completely erased to begin with. .end_defmetamethod

For example:

(defmethod (mumble-margin-mixin :compute-margins) 
	   (lm tm rm bm)
  (let ((wid (mumble-margin-width current-mumbles)))
    (setq mumble-margin-area
	  (list lm tm (+ lm wid) (- tv:height bm)))
    (values (+ lm wid) tm rm bm)))

Here we assume that the mumbles always go in the left margin. So it is always the left margin’s width that is incremented, and the others are returned just as they were passed. We also assume that mumble-margin-width is a function you have defined that computes the width of space that the mumbles need.

In addition to returning modified versions of its arguments, the method also sets up the value of mumble-margin-area. This is the only place it is necessary to set that variable. By recording the position of each margin item this way, we take into account how one margin item affects the position of the others. For example, the mumbles might come inside the borders, and then the lm, tm, rm and bm values will already contain the width of the borders. Then margin-mumble-area will describe a rectangle that is within the borders.

Usually an additional mixin-specific operation is introduced into this method, as follows:

(defmethod (mumble-margin-mixin :compute-margins)
	   (lm tm rm bm)
  (send self ':recalculate-mumble-margins lm tm rm bm))

(defmethod (mumble-margin-mixin :recalculate-mumble-margins) 
	   (lm tm rm bm)
  (let ((wid (mumble-margin-width current-mumbles)))
    (setq mumble-margin-area
	  (list lm tm (+ lm wid) (- tv:height bm)))
    (values (+ lm wid) tm rm bm)))

This way, other mixins can be defined to modify where the mumbles go by replacing the :recalculate-mumble-margins method.

The one other thing you must do is provide a method for :refresh-margins, to draw the mumbles in the rectangle recorded: You can assume that that rectangle is clear to start with.

(defmethod (mumble-margin-mixin :after :refresh-margins) ()
  (tv:sheet-force-access (self)
    (draw-mumbles current-mumbles mumble-margin-area)))

You may wish to provide the user with an operation to change the window’s mumbles. This operation should use the :redefine-margins operation.

.defmetamethod windows :redefine-margins This operation recomputes how much margin space is needed for all of the margin items, by invoking the :compute-margins operation, and then actually changes the window margin sizes if necessary.

If the margin sizes have changed, then the window is erased and :refresh-margins is done; the instance variable tv:restored-bits-p (present in all windows) is left set to nil. If the margin sizes have not changed, no output whatever is done, and tv:restored-bits-p is left set to t. All this is done using the :refresh operation. .end_defmetamethod

Here is an example of how to use it:

(defmethod (mumble-margin-mixin :set-mumbles) (new-mumbles)
  (setq current-mumbles
	(canonicalize-and-validate-mumble-spec new-mumbles))
  (send self ':redefine-margins)
  (when tv:restored-bits-p
    (tv:sheet-force-access (self)
      (erase-mumble-area mumble-margin-area)
      (draw-mumbles current-mumbles mumble-margin-area))))

The explicit erasure and drawing of the mumbles is done in the case where the total sizes of the margins have not changed (and therefore no screen updating has been done), in case the contents of the mumbles have changed.

12.1 Constraint Frames ¶

If you use Edit Screen to change the shape of an inspector or debugger window frame, the shapes of the panes are all changed so that the proportions come out looking as they are supposed to. If you play around with Edit Screen enough, you can even see the menus reformat themselves (changing their numbers of rows and columns) in order to keep all of their items visible. The way all this works is that the positions and shapes of the panes, instead of being explicitly specified in units of pixels, are specified symbolically. When the window changes shape, the symbolic description is elaborated again in light of the new shape, and the panes are reshaped appropriately.

This set of symbolic descriptions is called a set of constraints. When you make a constraint frame, you specify the configuration of panes within the frame by creating list structure to represent the layout. The format of this list structure is called the constraint language. It lets you say things like "give this pane one third of the remaining room, then give that pane 17 pixels, and then divide what remains between these two panes, evenly." The constraint language is fairly complex, and is described in full detail later. In general, a frame can have many different configurations. Each configuration is described in the constraint language, and each specifies one way of splitting up the frame. While the program is running, it can switch a frame from one configuration to another. Some panes may appear in more than one configuration, but other panes may be left out of one configuration, and may only be visible when the frame is switched to another configuration. For example, in ZMail, when you click on Profile, the frame changes to a new configuration whose panes include a profile editor window and another frame, the profile button frame.

• Constraint Frame Flavors
• Examples of Specifications of Panes and Constraints
• Specifying Panes and Constraints
• Constraint Frame Operations

(make-instance 'tv:constraint-frame
	       ':panes
		  '((top-pane tv:window)
		    (bottom-pane tv:window))
	       ':constraints
		  '((main . ((top-pane bottom-pane)
			     ((top-pane 0.5))
			     ((bottom-pane :even))))))

(make-instance 
  'tv:bordered-constraint-frame
  ':panes
    '((graphics-pane tv:window
	 :label nil :blinker-p nil)
      (message-pane tv:window
         :label "Message Pane" :blinker-p nil)
      (interaction-pane tv:window))
  ':constraints
    '((main . ((interaction-pane graphics-pane message-pane)
	       ((message-pane 4 :lines))
	       ((graphics-pane 400))
	       ((interaction-pane :even))))))

(make-instance
 'tv:bordered-constraint-frame
 ':panes
   '((huey tv:window)
     (dewey tv:window)
     (louie tv:window)
     (main-pane tv:window)
     (random-pane tv:window)
     (menu tv:command-menu
	   :item-list ("Foo" "Bar" "Baz")))
   ':constraints
     '((first-config . ((top-strip main-pane)
			((top-strip :horizontal (.3)
			  (huey dewey louie)
			  ((huey :even)
			   (dewey :even)
			   (louie :even))))
			((main-pane :even))))
       (second-config . ((main-pane bottom-strip)
			 ((bottom-strip :horizontal (.2)
			   (random-pane menu)
			   ((menu :ask :pane-size))
			   ((random-pane :even))))
			 ((main-pane :even))))))

  ':panes
     `((huey tv:window)
       (dewey tv:window)
       (louie tv:window)
       (main-pane tv:window)
       (random-pane tv:window)
       (menu tv:command-menu 
	     :item-list ,the-list-of-items))

(make-instance
  'tv:bordered-constraint-frame
  ':edges '(100 100 600 600)
  ':panes
    '((left tv:window)
      (right tv:window))
  ':constraints
    '((main . ((whole-thing)
	       ((whole-thing :horizontal (:even)
			     (left right)
			     ((left :even) 
			      (right :even))))))))

(name flavor . options)

((configuration-name-1 . configuration-description-1)
 (configuration-name-2 . configuration-description-2)
 ...)

(ordering . description-groups)

(pane-name . constraint)

(key arg-1 arg-2 ...)

(:limit limit-specification key arg-1 arg-2 ...)

12.2 Pane-Frame Interaction ¶

Several fundamental window operations actually ask the window’s superior what to do. This has no effect for a top-level window but becomes important when the window’s superior is a frame. The superior can decide whether the operations should actually go ahead as requested. These operations are :expose, :deexpose, :bury, :select and :set-edges. Here is how they are handled:

• :expose, :deexpose, :bury, :select These operations first send a message to the superior with operation :inferior-expose, :inferior-deexpose, :inferior-bury or :inferior-select. The pane itself is passed as the argument.

  If the message sent to the superior returns non-nil, the operation is performed on the pane as usual. Otherwise, it is skipped.

• :set-edges An :inferior-set-edges message is sent to the superior, its arguments being the pane followed by the arguments of the :set-edges message. If the operation’s first value is non-nil, the pane’s edges are changed as requested. Otherwise, the pane’s edges are not changed, and the remaining values from the :inferior-set-edges operation are returned from the :set-edges.

  Of course, the frame can change the pane’s edges in some other way and then return nil.

tv:basic-frame defines only the :inferior-select operation to do anything nontrivial; it makes the pane be the frame’s selection substitute and then sends a :select to the frame. The others operations do nothing but return non-nil. Thus, there is minimal interaction between the frame and its inferiors. tv:frame-forwarding-mixin defines :inferior-expose, :inferior-deexpose and :inferior-bury so that the frame and panes are all exposed together.

.defflavor tv:frame-forwarding-mixin Defines :inferior-expose, :inferior-deexpose, and :inferior-bury methods for a frame that normally cause :expose, :deexpose or :bury operations on panes to expose, deexpose or bury the frame rather than the pane.

An :inferior-set-edges method is also defined, for internal reasons only. Its purpose is to avoid a user-visible change in behavior rather than to provide one.

This flavor is part of tv:constraint-frame and the other standard instantiable flavors of constraint frame. .end_defflavor

tv:basic-frame has an instance variable tv:recursion which is used to distinguish between :expose, etc. operations sent by the frame’s code to its panes, and those sent by other programs. When an outside program sends a :expose, :deexpose, or :bury message to one of the panes, the :inferior-expose, etc. operation on the frame simply exposes, deexpose or buries the frame itself, and does not allow the operation on the pane to proceed. When the frame’s code itself exposes a pane, it does so with tv:recursion temporarily non-nil so that when the :inferior-expose is done it will return t and let the pane be exposed.

.defmetamethod frames :pane-types-alist This should return a menu item list to be used for the handling of the Create item in the screen editor, when editing the panes of this frame. The value of the menu item should be a flavor of window to create, or a list to be evaluated to return a flavor.

The menu item’s value (or the result of evaluating it) can also be t, which directs the screen editor to read a flavor name from the user. .end_defmetamethod

• The Selected Pane

(defmethod (my-frame :after :init) (ignore)
  (send self ':set-selection-substitute
	(send self ':get-pane 'interaction-pane)))

13.1 Notifications ¶

Notifications are asynchronous messages that come from something other than the selected window. For example, when an interactive message from another user comes in (which was sent with the qsend function), it is printed as a notification. You may have noticed that sometimes a notification is printed out immediately, while sometimes all that happens is a message in the who line. The selected window is responsible for deciding what to do with the notification.

Function: tv:notify window-of-interest format-string &rest format-args ¶

Function: tv:careful-notify window-of-interest careful-p format-string &rest format-args ¶

Make a notification. format-string and format-args are passed to format to print the text of the notification. Where this text is printed, and how, is under the control of the selected window, as described below.

window-of-interest is a window that should be selected if the user clicks the mouse on the notification window (if the notification happens to use its own window). For example, a notification about a message from another user will supply the Converse window as this argument. This window can also be selected with the Terminal 0 S command.

tv:careful-notify is different in that if careful-p is non-nil and the notification cannot be printed now because of windows being locked, it returns immediately. The value is non-nil if the notification was printed successfully.

.defmetamethod windows :print-notification time string window-of-interest The system invokes this operation on the selected window to ask it to make a notification. time will be a time to mention in the notification. string is the text to print. window-of-interest should be set up for the user to select in some convenient fashion, if possible. .end_defmetamethod

.defflavor tv:notification-mixin This mixin causes a window to handle notifications which happen while it is selected by printing them out on the window itself, if the window is big enough. Lisp listeners and typeout windows of all sorts use this mixin. .end_defflavor

.defmethod tv:notification-mixin :print-notification-on-self time string window-of-interest This operation does the actual work of printing a notification on the window itself, once it has been decided definitely to do so. It is sometimes useful for window flavors incorporating tv:notification-mixin to redefine this. .end_defmethod

.defflavor tv:delay-notification-mixin tv:delay-notification-mixin implements the default way of handling notifications: to make them wait. It is a component of tv:window, and also of anything that contains tv:select-mixin. tv:notification-mixin works by overriding it.

If a notification arrives while a window of this sort is selected, it is put on a list called tv:pending-notifications. All that happens immediately is a beep. But the presence of a non-nil value for this variable causes the mouse documentation line to display a message that there are notifications waiting, with blinking asterisks at each end of the line.

As soon as a window that can print the notifications is selected, they will be printed. For example, selecting a Lisp listener will do it. If you are in the editor, selecting the typeout window by typing Break will do it. There is also a command, Terminal N, which selects a window that just prints the notifications.

Alternatively, Terminal 2 N can be used to make the mouse documentation line go back to its normal function. This works by transferring everything on tv:pending-notifications onto another list, tv:deferred-notifications. These deferred notifications will still be printed if you switch to a suitable window. .end_defflavor

Another way a window can handle a notification is to ask some other window to do so. For example, editor windows (zwei:zmacs-window-pane) ask the containing Zmacs frame to do the job, and it in turn asks the echo area window to do it. This window displays the notification itself if the notification fits.

Function: tv:find-process-in-error ¶

Returns a process that has got an error and is waiting, having made a notification, for a window to be selected so the debugger can be run. If no such process is waiting, returns nil. If there are several such processes, the most recent one to make its notification is returned. The window the process is waiting for selection of is returned as the second value.

Function: tv:choose-process-in-error ¶

Similar to tv:find-process-in-error but asks the user about each candidate process. When the user answers Y, that process is returned. If the user answers N to each candidate, the value is nil. The window the process is waiting for selection of is returned as the second value.

Function: tv:print-notifications ¶

Prints on standard-output all the notifications that have happened in this session.

.defmetamethod windows :notice event The :notice operation is used to report certain events so that flavors can redefine what to do when they happen. The argument to :notice is an event name, a keyword. Additional arguments are allowed but have no meaning for any of the events yet defined. Here are the defined events:

• :input :notice
• :output :notice The window is being used for input (output) and is not exposed, and its deexposed input (output) action is :notify. The default action is to make a notification and wait.
• :input-wait :notice The window is being used for input and the process is waiting because no input is available now. The default action is to adjust the vertical position at which the next **MORE** will happen.
• :error :notice The window is being used for the debugger and is not exposed. The default action is to make a notification and wait, or to get another window if this one is too small.

The :notice operation uses :or method combination: all the methods are run until one returns non-nil. Aside from that, the value returned is not meaningful. .end_defmetamethod

13.2 Lisp Listeners ¶

.defflavor tv:lisp-listener This flavor of window is used for the window initially selected when the system starts up, and for windows created when you ask to create a "Lisp" window with any of the system menu commands. .end_defflavor

Variable: tv:initial-lisp-listener ¶

The Lisp listener window that is selected when you boot.

Function: tv:idle-lisp-listener &optional screen. ¶

Returns a Lisp listener which is waiting for input at top level, and is the full size of the specified screen. The screen defaults to tv:default-screen ((tv:default-screen-var)).

.defflavor tv:lisp-interactor This flavor of window works just like a Lisp listener, but System L will not select this kind of window, nor will tv:idle-lisp-listener return one. .end_defflavor

The mixin primarily responsible for making a Lisp listener behave the way it does is tv:listener-mixin-internal.

.defflavor tv:listener-mixin-internal This contains tv:process-mixin, and arranges by default for the process to be initialized to run the Lisp top level read-eval-print loop si:lisp-top-level1. .end_defflavor

.defmethod tv:listener-mixin-internal :package .defmethod1 tv:listener-mixin-internal :set-package package Get or set the package being used by the read-eval-print loop. These work by interfacing with some complicated code in tv:lisp-top-level1. The value from :package can be nil. When you set the package, either a package or a package name is acceptable.

These operations communicate with the process running the read-eval-print loop to access that process’s own binding of package. .end_defmethod

.defflavor tv:listener-mixin This flavor inherits its entire definition from tv:listener-mixin-internal. The only difference is that System L is defined to look for windows with this flavor, and not the other. .end_defflavor

13.3 Editor Windows ¶

.defflavor zwei:zmacs-frame This is the flavor of the window you get when you type System E. It has its own process, and can select any Zmacs buffer. Generally none of the editor-specific operations should be invoked on this window; that should be left up to the window’s own process. Requests to this process, which generally ask the process to select a buffer, are passed to it as blips of the form

(:execute zwei:edit-thing spec)

where spec is anything valid as the argument to ed. .end_defflavor

A Zmacs frame is useful for providing the user an opportunity to edit whatever he likes. Sometimes it is useful for a program to offer the user specific text to edit for its own purposes.

.defflavor zwei:standalone-editor-window This is a window with no panes that serves as an editor. It has a minibuffer and type-in window that pop up as its inferiors when they are needed. This window has no process of its own; use the :edit operation in any process to do editing in the window. .end_defflavor

.defflavor zwei:standalone-editor-frame Another kind of standalone editor window, but this one is a frame with a permanently visible mode line and typein-window or mini buffer, just as a Zmacs frame is. .end_defflavor

.defmetainitoption "standalone editor windows" :comtab comtab Specifies the comtab to use in editing in this frame. The default is zwei:*standalone-comtab*. .end_defmetainitoption

.defmetamethod "standalone editor windows" :edit Invokes the editor command loop on this window. The End command will return. .end_defmetamethod

.defmetamethod "editor windows" :interval-string Returns a string giving the current text in the window. .end_defmetamethod

.defmetamethod "editor windows" :set-interval-string string Sets the text in the window to string. .end_defmetamethod

.defmetamethod "editor windows" :interval Returns the interval which is being edited in the window. If the window is a Zmacs frame, this is the selected buffer. Standalone editor windows have their own nonshared intervals which they edit; many of the editor primitives that work on Zmacs buffers also work on these intervals. .end_defmetamethod

.defmetamethod "editor windows" :set-interval interval Sets the interval that this window is displaying and editing to interval. On a Zmacs window, interval must be a Zmacs buffer; then this will actually tell the window to select the new buffer. .end_defmetamethod

.defflavor zwei:pop-up-standalone-editor-frame A temporary window form of zwei:standalone-editor-frame. .end_defflavor

.defresource zwei:pop-up-standalone-editor-frame &optional (superior tv:mouse-sheet) A resource of such windows, used by the following function. .end_defresource

Function: zwei:pop-up-edstring string &optional (near-mode '(:mouse)) mode-line-list min-width min-height initial-message (comtab zwei:*standalone-comtab*) ¶

Pops up an editor window containing string and let the user edit it. When he types End, returns a string giving whatever he left in the editor buffer. If he types Abort, the value is nil.

near-mode specifies how to position the window before popping it up. It is passed to tv:expose-window-near.

mode-line-list is a list to be used to drive the mode line.

min-width and min-height are minimums for the size of the window. The window is larger than that if string requires more space to display.

initial-message, if non-nil, is displayed in the typein window immediately after the frame pops up.

comtab is the comtab to be used for editing.

.defflavor zwei:editor-top-level This is the flavor used by the Lisp (Edit) window which you can create with the system menu Create option. It is a kind of Lisp listener in which both the input and the output are recorded in an editor interval and can be edited. It is based on zwei:standalone-editor-window. .end_defflavor

.defresource zwei:temporary-mode-line-window-with-borders-resource &optional (superior tv:mouse-sheet) A resource of such windows, used by the following functions. .end_defresource

.defflavor zwei:temporary-mode-line-window-with-borders The temporary mode line window contains just a mode line and a mini buffer. It is a way for a program to request a small piece of input while allowing the user to edit with Zwei.

This is the flavor of window that you get in ZMail if you click right on Select in the ZMail command menu and then click on Find File in the Select menu. .end_defflavor

Function: zwei:typein-line-readline-near-window window format-string &rest format-args ¶

Pops up a temporary mode line window near window, displaying its mode line by passing format-string and format-args to format, and lets the user edit. Return terminates editing. The user’s input is returned as a string. window may be any window on the screen, or :mouse, meaning pop up near the mouse.

Function: zwei:read-defaulted-pathname-near-window window prompt defaults special-type ¶

Pops up a temporary mode line window near window, displaying the string prompt as the mode line, and lets the user edit text which (when the user types Return) is parsed into a pathname using defaults and special-type. window may be any window on the screen, or :mouse, meaning pop up near the mouse.

.defmethod zwei:temporary-mode-line-window-with-borders :call-mini-buffer-near-window window function &rest args Pops up this window near window, then uses function to read the input and returns the value it returns. function should be an editor function which invokes the mini buffer using zwei:edit-in-mini-buffer. The first argument to function is a stream reading from the text the user edited. args are passed to function as additional arguments. .end_defmethod

13.4 Window Flavors for Other Programs ¶

.defflavor tv:peek-frame This flavor of window is a self-contained Peek display with its own process to update it. .end_defflavor

.defflavor tv:inspect-frame This flavor of window is a self-contained inspector with its own process to update it. .end_defflavor

.defresource tv:inspect-frame-resource &optional (superior tv:mouse-sheet) A resource of inspector frames which are created in a slightly special way so that they do not have their own processes, but instead are to be invoked in some other process by the function inspect. .end_defresource

.defflavor supdup:supdup A self-contained Supdup window with its own pair of processes to transfer data to and from the network. .end_defflavor

.defflavor supdup:telnet A self-contained Telnet window with its own pair of processes to transfer data to and from the network. .end_defflavor

.defresource supdup:supdup-windows &optional (superior tv:mouse-sheet) .defresource1 supdup:telnet-windows &optional (superior tv:mouse-sheet) Resources of Supdup and Telnet windows, for use by the functions supdup and telnet when operating in the mode of substituting for another window. .end_defresource

.defflavor tv:pop-up-text-window A temporary window, otherwise like tv:window. .end_defflavor

.defresource tv:pop-up-text-window &optional (superior tv:mouse-sheet) A resource of such windows. .end_defresource

.defflavor tv:truncating-pop-up-text-window A temporary window which truncates lines of output, otherwise like tv:window. .end_defflavor

.defflavor tv:truncating-pop-up-text-window-with-reset Like tv:pop-up-text-window but truncates lines and resets the associated process when deexposed. This is the kind of window that Terminal F uses to print its output, and it is good for many similar applications. .end_defflavor

.defresource tv:pop-up-finger-window &optional (superior tv:mouse-sheet) A resource of such windows. .end_defresource

13.5 The Who Line ¶

The who line is the pair of lines at the bottom of the main Lisp Machine screen which display the current status of the machine. The first of the two lines displays documentation what mouse clicks would do at the present time, based on the actual position of the mouse. The second line displays the time, your login name, the current process’s package and run state, and file or net server information. The term "who line" is sometimes used to refer to this line alone.

The window system treats the who line as a separate screen, thus preventing windows on the rest of the screen from being moved or reshaped to overlap the who line. The mouse documentation line is displayed by a window of its own, and so is each field of the second line.

The documentation displayed by the mouse documentation line is obtained by sending the window under the mouse a :who-line-documentation-string message (see (windows-who-line-documentation-string-method)), or from the variable tv:who-line-mouse-grabbed-documentation when the mouse is grabbed (see (tv:who-line-mouse-grabbed-documentation-var)).

Function: tv:who-line-documentation t-or-nil ¶

Turns the who line display of mouse documentation on or off.

The package name and run state displayed in the who line describe only one process. They normally describe the process associated with the selected window, which is a different process if a new window is selected. However, the who line can be fixated on a particular process, independent of the selected window.

Variable: tv:who-line-process ¶

The process to describe in the who line, or nil meaning to display the one associated with the selected window. In the latter case, the :process operation on the window is used to get the process to display.

Variable: tv:last-who-line-process ¶

The process most recently described in the who line, regardless of why that process was chosen. May be nil if there was no process to describe (for example, if the who line was supposed to describe the selected window but there was no selected window or the window had no process).

The user can set tv:who-line-process using the Terminal W command (see "Operating the Lisp Machine").

Function: tv:who-line-clobbered ¶

Informs the who line that it must redisplay everything.

Recording open file streams for display:

Function: tv:who-line-file-state-sheet ¶

This who line window displays the status of an open stream or active network server. It can also display the idle time if there is no stream or server.

This window is also responsible for maintaining the lists of streams and servers that could be displayed. New streams and servers are reported to it with operations described here.

.defmethod tv:who-line-file-sheet :add-stream stream update-p Adds stream to the list of open streams recorded by the file state sheet. If update-p is non-nil, the who line field is updated immediately. .end_defmethod

.defmethod tv:who-line-file-sheet :delete-stream stream Removes stream from the list of streams for the who line. .end_defmethod

.defmethod tv:who-line-file-sheet :delete-all-streams Clears out the list of streams for the who line. .end_defmethod

.defmethod tv:who-line-file-sheet :open-streams Returns the list of streams recorded for the who line. .end_defmethod

When the who line describes an open file, the name to display for it is obtained with the :string-for-wholine pathname operation. See (fs:pathname-string-for-wholine-method).

.defmethod tv:who-line-file-sheet :add-server conn contact-name process function Adds a entry to the list of active network servers recorded by the file state sheet. conn should be the network connection of this server, contact-name the contact name it responded to, process the process the server is running in. .end_defmethod

.defmethod tv:who-line-file-sheet :delete-server conn Removes the entry for connection conn from the list of servers for the who line. Note that this happens automatically if the connection is broken or closed. .end_defmethod

.defmethod tv:who-line-file-sheet :delete-all-servers Clears out the list of servers for the who line. .end_defmethod

Function: tv:close-all-servers &optional (reason "Foo on you") ¶

Closes the connections of all network servers, giving reason (a string) as the reason in the CLS packet.

Function: tv:describe-servers ¶

Prints descriptions of all active network servers.

13.6 The Color Screen ¶

The usual color screen on a Lisp Machine has 454. lines of 576. pixels each, and each pixel has four bits. This allows sixteen different colors to be displayed at once. There are far more than sixteen possible colors. A color map controls the meaning of each of the sixteen pixel values. Each of the sixteen color map slots specifies an eight-bit red intensity, an eight-bit green intensity, and an eight-bit blue intensity. Thus there are about 16 million different colors that can appear, but only sixteen can be displayed at once.

Variable: color:color-screen ¶

The screen object that represents the color screen. This object is always present whether the machine has a color screen or not.

Function: color:color-exists-p ¶

t if this machine actually has a color screen.

• Color Map Functions
• Operating on Pixels

13.7 The System Menu ¶

This section describes how to interface with and customize the system menu which pops up when you click twice on the right mouse button.

The system menu is an instance of flavor tv:dynamic-multicolumn-momentary-window-hacking-menu (see (tv:dynamic-multicolumn-momentary-window-hacking-menu-flavor)), which means that its menu items are grouped by columns, and each column’s items come from the value of a corresponding variable which is examined each time the menu is popped up in case more items have been added. This is to enable you to add items to the menu and control where they go. The most common column to add to is the third one, which lists various kinds of windows to select (somewhat like the System command), so a special interface is provided for adding to it.

Function: tv:add-to-system-menu-programs-column name form documentation &optional after ¶

Adds an item named name to the third column of the system menu. form is what to execute if the user clicks on the item, and documentation is the mouse documentation string.

after is the name of an item to add after (a string), or t to add at the top, or nil to add at the bottom.

Variable: tv:*system-menu-windows-column* ¶

A menu item list which forms the first column of the system menu.

Variable: tv:*system-menu-this-window-column* ¶

A menu item list which forms the second column of the system menu. By convention this is used for things that operate on the window that the mouse was pointing at when the system menu was brought up. They are implemented with :window-op menu items.

The Select item in the system menu pops up a momentary menu with a list of windows that the user might want to select. Not all the visible windows are included; usually a team of windows belonging to a single program is represented by a single entry since selection among the team is controlled by the program rather than the user. See (select-menu), for full details.

The Create item in the system menu pops up a menu for the user to choose a flavor of window to create.

Variable: tv:default-window-types-item-list ¶

A menu item list that is used by the system menu Create option, and by Create in the screen editor when operating on a screen.

In general, the screen editor can operate on the inferiors of any window. Then, the :pane-types-alist operation on that window is used to get the item list for possible flavors to create; see (frames-pane-types-alist-method). On a screen, the operation returns the value of this variable.

13.8 Window Resources ¶

A resource is a pool of interchangeable objects that are available to be used temporarily and then returned to the pool (see (defresource-fun). Read that before you continue here).

Resources whose objects are windows are often useful. For example, there is a resource of windows of the right flavor to serve as "the system menu"; when you invoke "the" system menu, a window is allocated from the resource, and it is returned to the resource’s pool when it is deactivated.

Normally one defines a resource with defresource. If the objects in the resource are windows, it is better to use instead a different function, tv:defwindow-resource. Allocating windows from resources, and returning them, is just like working with any other resources, and is documented in the Lisp Machine manual.

All the names described in this manual as resources are defined in this way.

Special Form: tv:defwindow-resource name parameters &rest options ¶

Defines a resource of windows, named name. parameters are parameters on which the object can depend. Following the parameters specified is one additional parameter that is always defined: the window’s superior. When you allocate a window from the resource, this parameter defaults to tv:mouse-sheet.

options is a list of alternating keywords and values. Neither the keywords nor the values are evaluated at the time that tv:defwindow-resource is executed, but sometimes the value becomes part of an expression that will be executed later (when a window is allocated from the resource).

The allowed keywords are

• :initial-copies The value is the number of windows to create in the resource when the resource is defined. The default is one. The initial copies are made inferiors of tv:default-screen. Creating an initial copy is just a way of saving time the first time a window needs to be allocated from the resource.
• :constructor See the definition of defresource. If it is not specified, tv:defwindow-resource provides a default, which calls make-instance with arguments taken from the :make-window option.
• :make-window The value should be a list of a flavor name followed by keyword arguments. This list will be consed into a make-window form to get the constructor for the resource.
• :reusable-when The value should be :deexposed, :deactivated. If this keyword is not specified, then windows of the resource can be allocated to requesters if they have been explicitly returned to the pool and are not locked. :deexposed means that any window that is not exposed is considered to have been returned to the pool. :deactivated means that any window that is not active is considered to have been returned to the pool.

Variable: tv:window-resource-list ¶

A list of the names of all window resources defined with tv:defwindow-resource.

Example: the system menu is created thus:

;Resource of system menus
(defwindow-resource system-menu ()
  :make-window
  (dynamic-multicolumn-momentary-window-hacking-menu
    :column-spec-list
    '(("Windows" *system-menu-windows-column*
       :font fonts:hl12i)
      ("This window" *system-menu-this-window-column*
       :font fonts:hl12i)
      ("Programs" *system-menu-programs-column*
       :font fonts:hl12i))
    :save-bits t)
  :reusable-when :deexposed)

13.9 The Cold Load Stream ¶

User programs that make use of the screen organization and standardization facilities provided by the window system are frequently in a somewhat difficult position. If that interface to the window system does not work, there seems to be no way at all to find out what is going on. Similarly, debugging code associated with switching between windows can be difficult since there may be no place to print debugging output at the time such code is executing.

One way to debug such problems is to use the cold load stream. This is the stream used in constructing the initial Lisp Machine environment, before the window system itself has been loaded. It has the advantage that it does not attempt to interface with the rest of the window system, or vice versa. It will never deexpose any windows or lock any locks. It types out one character at a time, by calling the microcode directly, and has very simple-minded ideas about end of line exceptions and more breaks.

Variable: tv:cold-load-stream ¶

The cold load stream is the value of this variable.

When the cold load stream is "waiting" for type-in, it does not actually wait; in fact, it loops until a character appears, with scheduling turned off, blinking its own special blinker by hand. The who line is not updated. Also, the chaosnet processes do not get to run. If the machine stays in this state too long, all chaosnet connections will be lost.

Whenever the system gets an error in the keyboard process, the scheduler or the mouse process, the debugger uses the cold-load-stream rather than terminal-io. You also have the option of requesting this if there is an error in a process whose terminal-io is a window that is not exposed and cannot be exposed because of locked windows. (You will be queried, using the cold load stream, to choose between this and a couple of other possibilities.)

When you exit from the debugger after it was using the cold load stream for one of these reasons, it will ask you whether to "restore the screen". Normally you should say Yes; then the screen contents will go back to what they were before the debugger was entered.

It is often preferable to use the cold load stream for debugging window problems even when the normal alternatives are available. This is because the operation of the debugger using a window for I/O may interfere with the window phenomena being debugged. Use of the cold load stream will avoid these problems. You can request use of the cold load stream by setting debug-io to the value of tv:cold-load-stream before you run your test. Once this has been done, not only errors but breakon and Meta-Break as well will use the cold load stream. To turn off use of the cold load stream for all debugger invocations, set debug-io back to nil.

You can also force trace output into the cold load stream by setting trace-output. Note that you must not set trace-output to nil when done; you must save its original value and set it back to that.

When the cold load stream is used because you have set one of the stream variables to it, you do not get the chance to restore the screen. It is not so easy to define how to do that "right" in this case; if it were done after each exit from the debugger, you would not get to see the history of multiple entries to the debugger.

The program can invoke a break loop using the cold load stream by calling tv:kbd-use-cold-load-stream. Type Resume to continue. Note that when the break is entered, the package you are typing into is typed out, because the package in the who-line is not going to be correct for this break loop.

You the user can request such a break loop by typing Terminal Call or by clicking on Emergency Break item in the system menu. You can get your program into the debugger using the cold load stream, without having made advance preparation, by getting a break loop in this fashion, setting debug-io to the cold load stream, exiting, and typing Meta-Break.

Also, it is often useful to get a cold load stream break loop and call eh on various processes or stack groups.

13.10 The Window-Based Debugger ¶

The window-based debugger is an alternative to the usual debugger; it performs the same functions but displays graphically rather than using sequential stream I/O. You invoke the window-based debugger by typing Control-Meta-W while in the usual debugger. You can switch back and forth between the two debuggers any number of times while handling a single error.

The debugger window is divided into six panes. At the bottom is a Lisp-listener-like window, which ordinarily provides a read-eval-print loop similar to the regular keyboard debugger. More commands are available by using the mouse in the other windows as described below.

At the top is a display of the disassembled or ground code for the currently selected stack frame, depending on whether or not it is compiled. It has a scroll-bar, but is otherwise not sensitive to the mouse.

Next are the args and locals windows, side by side, displaying the names and values of the arguments to the current stack frame and its local variables; they are grayed out if there are none. They also have scroll bars. Clicking the mouse on the name of an argument will print the name and the value in the Lisp window. Clicking on just the value will print it in the Lisp window. The mouse will highlight any relevant quantity that you are pointing to.

Next is the stack window, which displays in a pseudo-list format the functions and arguments on the stack. Clicking on a function or argument or sublists of them will cause them to be printed in the Lisp window as in the argument or local windows. Also, clicking the mouse to the left of a line containing a particular stack frame will make the debugger select that frame, changing what the above three windows show.

Below this, and above the Lisp window, is the command menu for the debugger window. The available commands are:

• What error Reprints the error message for the current error, in the Lisp window.
• Exit Window EH Exits the debugger window, returning to the regular debugger.
• Abort Program Like Abort in the regular debugger.
• Arglist Asks for the name of a function, which can be typed on the keyboard, or moused if it is on the screen. Picking an actor or a closure will ask for the message name to that actor and print the arguments to its method for that message. Picking a line of a stack frame from the stack window will try to align the printout of the arguments with what value was supplied in that position in that frame.
• Edit Reads a name of a function in the same fashion as the Arglist command and invokes the editor on that function.
• Retry Attempts to restart the current frame, like the Control-Meta-R command in the regular debugger.
• Return a Value Asks for the name of a value (which can be selected with the mouse) and returns it from the current frame, like Control-R in the regular debugger.
• Proceed Proceeds from the error. Clicking left on Proceed is like typing Resume in the regular debugger. Clicking right on Proceed gets you a menu of available proceed types, from which you can select one. This is equivalent to using one of the available Super commands in the regular debugger. If proceeding asks for an object to return, you can specify it with keyboard input or by pointing to a value with the mouse.
• Set arg Select an argument or local with the mouse and type or mouse a new value to be substituted in.
• Search Like the Control-S command, except that the mouse can be used.
• Throw Like Control-T in the regular debugger, it asks for a tag and a value and throws there. The mouse can be used to specify the tag and value.
• T
• NIL Ordinarily just supply those symbols as arguments or values for other commands. These can also be used to answer yes-or-no questions.

14.1 Menus ¶

A menu is an array of choices, each identified by a word or short phrase. You can select one of the choices by moving the mouse near it, which causes it to be highlighted (a box appears around it), and then clicking any mouse button.

What happens when you select one of the choices depends on the particular type of menu. Typically the choices in a menu might be commands to some program or choices for what a command should operate upon.

The system automatically chooses the arrangement of the choices and the size and shape of the window. Naturally there are ways for the user to control this if necessary.

To see an example of a menu, click the right-hand mouse button twice, causing the system menu to appear.

• Menu Items
• Easy Menu Interface
• Geometry
• Ordinary Menus
• Command Menus
• Dynamic Item List Menus
• Multiple Menus