Changes between Initial Version and Version 1 of HemlockProgrammer/ControllingTheDisplay


Ignore:
Timestamp:
Nov 4, 2007, 2:17:11 AM (13 years ago)
Author:
rme
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • HemlockProgrammer/ControllingTheDisplay

    v1 v1  
     1[[PageOutline]]
     2
     3= 10. Controlling the Display =
     4== 10.1. Windows ==
     5
     6A window is a mechanism for displaying part of a buffer on some
     7physical device.  A window is a way to view a buffer but is not
     8synonymous with one; a buffer may be viewed in any number of windows.
     9A window may have a modeline which is a line of text displayed across
     10the bottom of a window to indicate status information, typically
     11related to the buffer displayed.
     12
     13== 10.2. The Current Window ==
     14
     15current-window [Function]
     16
     17Set Window Hook [Hemlock Variable]
     18
     19current-window returns the window in which the cursor is currently
     20displayed.  The cursor always tracks the buffer-point of the
     21corresponding buffer.  If the point is moved to a position which would
     22be off the screen the recentering process is invoked.  Recentering
     23shifts the starting point of the window so that the point is once
     24again displayed.  The current window may be changed withsetf. Before
     25the current window is changed, the hook Set Window Hook is invoked with
     26the new value.
     27
     28*window-list* [Variable]
     29
     30Holds a list of all the window objects made with make-window (page 41).
     31
     32== 10.3. Window Functions ==
     33
     34make-window mark &key :modelinep :window :ask-user [Function]
     35:x :y :width :height
     36
     37Default Window Width [Hemlock Variable]
     38
     39Default Window Height [Hemlock Variable]
     40
     41Make Window Hook [Hemlock Variable]
     42
     43make-window returns a window displaying text starting at mark, which
     44must point into a buffer.  If it could not make a window on the
     45device, it returns nil.  The default action is to make the new window
     46a proportion of the current-window's height to make room for the new
     47window.
     48
     49Modelinep specifies whether the window should display buffer modelines.
     50
     51Window is a device dependent window to be used with the Hemlock
     52window.  The device may not support this argument. Window becomes the
     53parent window for a new group of windows that behave in a stack
     54orientation as windows do on the terminal.
     55
     56If ask-user is non-nil, Hemlock prompts the user for the missing
     57dimensions (x, y, width, and height) to make a new group of windows,
     58as with the window argument. The device may not support this argument.
     59Non-null values other thantmay have device dependent meanings. X and y
     60are in pixel units, but width and height are characters units. Default
     61Window Width and Default Window Height are the default values for the
     62width and height arguments.
     63
     64Proportion determines what proportion of the current-window's height
     65the new window will use.  The current-window retains whatever space
     66left after accommodating the new one.  The default is to split the
     67window in half.
     68
     69This invokes Make Window Hook with the new window.
     70
     71windowp window [Function]
     72
     73This function returns t if window is a window object, otherwise nil.
     74
     75delete-window window [Function]
     76
     77Delete Window Hook [Hemlock Variable]
     78
     79delete-window make swindow go away, first invoking Delete Window Hook
     80with window.
     81
     82window-bufferwindow [Function]
     83
     84Window Buffer Hook [Hemlock Variable]
     85
     86window-buffer returns the buffer from which the window displays
     87text. This may be changed with setf, in which case the hook Window
     88Buffer Hook is invoked beforehand with the window and the new buffer.
     89
     90window-display-start window [Function]
     91
     92window-display-end window [Function]
     93
     94window-display-start returns the mark that points before the first
     95character displayed in window.  Note that if window is the current
     96window, then moving the start may not prove much, since recentering
     97may move it back to approximately where it was originally.
     98window-display-end is similar, but points after the last character
     99displayed.  Moving the end is meaningless, since redisplay always
     100moves it to after the last character.
     101
     102window-display-recentering window [Function]
     103
     104This function returns whether redisplay will ensure the buffer's point
     105of window's buffer is visible after redisplay. This is setf-able, and
     106changing window's buffer sets this to nil via Window Buffer Hook.
     107
     108window-point window [Function]
     109
     110This function returns as a mark the position in the buffer where the
     111cursor is displayed.  This may be set with setf. If window is the current
     112window, then setting the point will have little effect; it is forced
     113to track the buffer point. When the window is not current, the window
     114point is the position that the buffer point will be moved to when the
     115window becomes current.
     116
     117center-window window mark [Function]
     118
     119This function attempts to adjust window's display start so the that
     120markis vertically centered within the window.
     121
     122scroll-window window n [Function]
     123
     124This function scrolls the window down n display lines; if n is
     125negative scroll up.  Leave the cursor at the same text position unless
     126we scroll it off the screen, in which case the cursor is moved to the
     127end of the window closest to its old position.
     128
     129displayed-p mark window [Function]
     130
     131Returns t if either the character before or the character after mark
     132is being displayed inwindow, or nil otherwise.
     133
     134window-height window [Function]
     135
     136window-width window [Function]
     137
     138Height or width of the area of the window used for displaying the
     139buffer, in character positions.  These values may be changed with
     140setf, but the setting attempt may fail, in which case nothing is done.
     141
     142next-window window [Function]
     143
     144previous-window window [Function]
     145
     146Return the next or previous window of window. The exact meaning of
     147next and previous depends on the device displaying the window.  It
     148should be possible to cycle through all the windows displayed on a
     149device using either next or previous (implying that these functions
     150wrap around.)
     151
     152== 10.4. Cursor Positions ==
     153
     154A cursor position is an absolute position within a window's coordinate
     155system.  The origin is in the upper-left-hand corner and the unit is
     156character positions.
     157
     158mark-to-cursorpos mark window [Function]
     159
     160Returns as multiple values the X and Y position on which mark is being
     161displayed in window, or nil if it is not within the bounds displayed.
     162
     163cursorpos-to-mark X Y window [Function]
     164
     165Returns as a mark the text position which corresponds to the given (X,
     166Y) position within window, or nil if that position does not correspond
     167to any text within window.
     168
     169last-key-event-cursorpos [Function]
     170
     171Interprets mouse input.  It returns as multiple values the (X, Y)
     172position and the window where the pointing device was the last time
     173some key event happened. If the information is unavailable, this
     174returns nil.
     175
     176mark-column mark [Function]
     177
     178This function returns the X position at which mark would be displayed,
     179supposing its line was displayed on an infinitely wide screen.  This
     180takes into consideration strange characters such as tabs.
     181
     182move-to-column mark column &optional line [Function]
     183
     184This function is analogous to move-to-position (page 5), except that
     185it moves markto the position on line which corresponds to the
     186specified column. Line defaults to the line that mark is currently on.
     187If the line would not reach to the specified column, then nil is
     188returned and mark is not modified.  Note that since a character may be
     189displayed on more than one column on the screen, several different
     190values of column may cause mark to be moved to the same position.
     191
     192show-mark mark window time [Function]
     193
     194This function highlights the position of mark within window for time
     195seconds, possibly by moving the cursor there. The wait may be aborted
     196if there is pending input.  If mark is positioned outside the text
     197displayed by window, then this returns nil, otherwise t.
     198
     199== 10.5. Redisplay ==
     200
     201Redisplay translates changes in the internal representation of text
     202into changes on the screen.  Ideally this process finds the minimal
     203transformation to make the screen correspond to the text in order to
     204maximize the speed of redisplay.
     205
     206redisplay [Function]
     207
     208Redisplay Hook [Hemlock Variable]
     209
     210redisplay executes the redisplay process, and Hemlock typically
     211invokes this whenever it looks for input. The redisplay process
     212frequently checks for input, and if it detects any, it aborts. The
     213return value is interpreted as follows:
     214
     215 * nil No update was needed.
     216 * t Update was needed, and completed successfully.
     217 * :editor-input Update is needed, but was aborted due to pending input.
     218
     219This function invokes the functions in Redisplay Hook on the current
     220window after computing screen transformations but before executing
     221them.  After invoking the hook, this recomputes the redisplay and then
     222executes it on the current window.
     223
     224For the current window and any window with window-display-recentering
     225set, redisplay ensures the buffer's point for the window's buffer is
     226visible after redisplay.
     227
     228redisplay-all [Function]
     229
     230This causes all editor windows to be completely redisplayed.  For the
     231current window and any window with window-display-recentering set, this
     232ensures the buffer's point for the window's buffer is visible after
     233redisplay.  The return values are the same as for redisplay, except
     234that nil is never returned.
     235
     236editor-finish-output window [Function]
     237
     238This makes sure the editor is synchronized with respect to redisplay
     239output towindow. This may do nothing on some devices.
     240