wiki:HemlockProgrammer/ControllingTheDisplay

Version 1 (modified by rme, 7 years ago) (diff)

--

10. Controlling the Display

10.1. Windows

A window is a mechanism for displaying part of a buffer on some physical device. A window is a way to view a buffer but is not synonymous with one; a buffer may be viewed in any number of windows. A window may have a modeline which is a line of text displayed across the bottom of a window to indicate status information, typically related to the buffer displayed.

10.2. The Current Window

current-window [Function]

Set Window Hook [Hemlock Variable]

current-window returns the window in which the cursor is currently displayed. The cursor always tracks the buffer-point of the corresponding buffer. If the point is moved to a position which would be off the screen the recentering process is invoked. Recentering shifts the starting point of the window so that the point is once again displayed. The current window may be changed withsetf. Before the current window is changed, the hook Set Window Hook is invoked with the new value.

*window-list* [Variable]

Holds a list of all the window objects made with make-window (page 41).

10.3. Window Functions

make-window mark &key :modelinep :window :ask-user [Function] :x :y :width :height

Default Window Width [Hemlock Variable]

Default Window Height [Hemlock Variable]

Make Window Hook [Hemlock Variable]

make-window returns a window displaying text starting at mark, which must point into a buffer. If it could not make a window on the device, it returns nil. The default action is to make the new window a proportion of the current-window's height to make room for the new window.

Modelinep specifies whether the window should display buffer modelines.

Window is a device dependent window to be used with the Hemlock window. The device may not support this argument. Window becomes the parent window for a new group of windows that behave in a stack orientation as windows do on the terminal.

If ask-user is non-nil, Hemlock prompts the user for the missing dimensions (x, y, width, and height) to make a new group of windows, as with the window argument. The device may not support this argument. Non-null values other thantmay have device dependent meanings. X and y are in pixel units, but width and height are characters units. Default Window Width and Default Window Height are the default values for the width and height arguments.

Proportion determines what proportion of the current-window's height the new window will use. The current-window retains whatever space left after accommodating the new one. The default is to split the window in half.

This invokes Make Window Hook with the new window.

windowp window [Function]

This function returns t if window is a window object, otherwise nil.

delete-window window [Function]

Delete Window Hook [Hemlock Variable]

delete-window make swindow go away, first invoking Delete Window Hook with window.

window-bufferwindow [Function]

Window Buffer Hook [Hemlock Variable]

window-buffer returns the buffer from which the window displays text. This may be changed with setf, in which case the hook Window Buffer Hook is invoked beforehand with the window and the new buffer.

window-display-start window [Function]

window-display-end window [Function]

window-display-start returns the mark that points before the first character displayed in window. Note that if window is the current window, then moving the start may not prove much, since recentering may move it back to approximately where it was originally. window-display-end is similar, but points after the last character displayed. Moving the end is meaningless, since redisplay always moves it to after the last character.

window-display-recentering window [Function]

This function returns whether redisplay will ensure the buffer's point of window's buffer is visible after redisplay. This is setf-able, and changing window's buffer sets this to nil via Window Buffer Hook.

window-point window [Function]

This function returns as a mark the position in the buffer where the cursor is displayed. This may be set with setf. If window is the current window, then setting the point will have little effect; it is forced to track the buffer point. When the window is not current, the window point is the position that the buffer point will be moved to when the window becomes current.

center-window window mark [Function]

This function attempts to adjust window's display start so the that markis vertically centered within the window.

scroll-window window n [Function]

This function scrolls the window down n display lines; if n is negative scroll up. Leave the cursor at the same text position unless we scroll it off the screen, in which case the cursor is moved to the end of the window closest to its old position.

displayed-p mark window [Function]

Returns t if either the character before or the character after mark is being displayed inwindow, or nil otherwise.

window-height window [Function]

window-width window [Function]

Height or width of the area of the window used for displaying the buffer, in character positions. These values may be changed with setf, but the setting attempt may fail, in which case nothing is done.

next-window window [Function]

previous-window window [Function]

Return the next or previous window of window. The exact meaning of next and previous depends on the device displaying the window. It should be possible to cycle through all the windows displayed on a device using either next or previous (implying that these functions wrap around.)

10.4. Cursor Positions

A cursor position is an absolute position within a window's coordinate system. The origin is in the upper-left-hand corner and the unit is character positions.

mark-to-cursorpos mark window [Function]

Returns as multiple values the X and Y position on which mark is being displayed in window, or nil if it is not within the bounds displayed.

cursorpos-to-mark X Y window [Function]

Returns as a mark the text position which corresponds to the given (X, Y) position within window, or nil if that position does not correspond to any text within window.

last-key-event-cursorpos [Function]

Interprets mouse input. It returns as multiple values the (X, Y) position and the window where the pointing device was the last time some key event happened. If the information is unavailable, this returns nil.

mark-column mark [Function]

This function returns the X position at which mark would be displayed, supposing its line was displayed on an infinitely wide screen. This takes into consideration strange characters such as tabs.

move-to-column mark column &optional line [Function]

This function is analogous to move-to-position (page 5), except that it moves markto the position on line which corresponds to the specified column. Line defaults to the line that mark is currently on. If the line would not reach to the specified column, then nil is returned and mark is not modified. Note that since a character may be displayed on more than one column on the screen, several different values of column may cause mark to be moved to the same position.

show-mark mark window time [Function]

This function highlights the position of mark within window for time seconds, possibly by moving the cursor there. The wait may be aborted if there is pending input. If mark is positioned outside the text displayed by window, then this returns nil, otherwise t.

10.5. Redisplay

Redisplay translates changes in the internal representation of text into changes on the screen. Ideally this process finds the minimal transformation to make the screen correspond to the text in order to maximize the speed of redisplay.

redisplay [Function]

Redisplay Hook [Hemlock Variable]

redisplay executes the redisplay process, and Hemlock typically invokes this whenever it looks for input. The redisplay process frequently checks for input, and if it detects any, it aborts. The return value is interpreted as follows:

  • nil No update was needed.
  • t Update was needed, and completed successfully.
  • :editor-input Update is needed, but was aborted due to pending input.

This function invokes the functions in Redisplay Hook on the current window after computing screen transformations but before executing them. After invoking the hook, this recomputes the redisplay and then executes it on the current window.

For the current window and any window with window-display-recentering set, redisplay ensures the buffer's point for the window's buffer is visible after redisplay.

redisplay-all [Function]

This causes all editor windows to be completely redisplayed. For the current window and any window with window-display-recentering set, this ensures the buffer's point for the window's buffer is visible after redisplay. The return values are the same as for redisplay, except that nil is never returned.

editor-finish-output window [Function]

This makes sure the editor is synchronized with respect to redisplay output towindow. This may do nothing on some devices.