Changes between Version 1 and Version 2 of HemlockProgrammer/ControllingTheDisplay


Ignore:
Timestamp:
Jan 15, 2008, 4:28:19 PM (12 years ago)
Author:
gz
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • HemlockProgrammer/ControllingTheDisplay

    v1 v2  
     1[HemlockProgrammer Back to Table of Contents]
    12[[PageOutline]]
    23
    34= 10. Controlling the Display =
    4 == 10.1. Windows ==
    55
    6 A window is a mechanism for displaying part of a buffer on some
    7 physical device.  A window is a way to view a buffer but is not
    8 synonymous with one; a buffer may be viewed in any number of windows.
    9 A window may have a modeline which is a line of text displayed across
    10 the bottom of a window to indicate status information, typically
    11 related to the buffer displayed.
     6== 10.1. Views ==#Views
    127
    13 == 10.2. The Current Window ==
     8A `hemlock-view` represents the GUI object(s) used to display the contents
     9of a buffer.  Conceptually it consists of a text buffer, a
     10modeline for semi-permanent status info, an echo area for transient
     11status info, and a text input area for reading prompted
     12input. (Currently the last two are conflated, i.e. text input happens
     13in the echo area).
    1414
    15 current-window [Function]
     15The API for working with hemlock-views is not fully
     16defined yet.  If you need to work with views beyond what's listed
     17here, you will probably need to get in the sources and find some
     18internal functions to call.
    1619
    17 Set Window Hook [Hemlock Variable]
     20== 10.2. The Current View ==#CurrentView
    1821
    19 current-window returns the window in which the cursor is currently
    20 displayed.  The cursor always tracks the buffer-point of the
    21 corresponding buffer.  If the point is moved to a position which would
    22 be off the screen the recentering process is invoked.  Recentering
    23 shifts the starting point of the window so that the point is once
    24 again displayed.  The current window may be changed withsetf. Before
    25 the current window is changed, the hook Set Window Hook is invoked with
    26 the new value.
     22`current-view` [Function]
    2723
    28 *window-list* [Variable]
     24current-view returns the hemlock view which is the target of the
     25currently executing command.  This is usually the frontmost hemlock
     26window in the current application.
    2927
    30 Holds a list of all the window objects made with make-window (page 41).
     28== 10.3. View Functions ==#ViewFunctions
    3129
    32 == 10.3. Window Functions ==
     30`hemlock-view-p` object [Function]
    3331
    34 make-window mark &key :modelinep :window :ask-user [Function]
    35 :x :y :width :height
     32This function returns t if object is a hemlock view, otherwise nil.
    3633
    37 Default Window Width [Hemlock Variable]
     34`hemlock-view-buffer` view [Function]
    3835
    39 Default Window Height [Hemlock Variable]
     36This function returns the buffer which is displayed in the view.
    4037
    41 Make Window Hook [Hemlock Variable]
    4238
    43 make-window returns a window displaying text starting at mark, which
    44 must point into a buffer.  If it could not make a window on the
    45 device, it returns nil.  The default action is to make the new window
    46 a proportion of the current-window's height to make room for the new
    47 window.
    48 
    49 Modelinep specifies whether the window should display buffer modelines.
    50 
    51 Window is a device dependent window to be used with the Hemlock
    52 window.  The device may not support this argument. Window becomes the
    53 parent window for a new group of windows that behave in a stack
    54 orientation as windows do on the terminal.
    55 
    56 If ask-user is non-nil, Hemlock prompts the user for the missing
    57 dimensions (x, y, width, and height) to make a new group of windows,
    58 as with the window argument. The device may not support this argument.
    59 Non-null values other thantmay have device dependent meanings. X and y
    60 are in pixel units, but width and height are characters units. Default
    61 Window Width and Default Window Height are the default values for the
    62 width and height arguments.
    63 
    64 Proportion determines what proportion of the current-window's height
    65 the new window will use.  The current-window retains whatever space
    66 left after accommodating the new one.  The default is to split the
    67 window in half.
    68 
    69 This invokes Make Window Hook with the new window.
    70 
    71 windowp window [Function]
    72 
    73 This function returns t if window is a window object, otherwise nil.
    74 
    75 delete-window window [Function]
    76 
    77 Delete Window Hook [Hemlock Variable]
    78 
    79 delete-window make swindow go away, first invoking Delete Window Hook
    80 with window.
    81 
    82 window-bufferwindow [Function]
    83 
    84 Window Buffer Hook [Hemlock Variable]
    85 
    86 window-buffer returns the buffer from which the window displays
    87 text. This may be changed with setf, in which case the hook Window
    88 Buffer Hook is invoked beforehand with the window and the new buffer.
    89 
    90 window-display-start window [Function]
    91 
    92 window-display-end window [Function]
    93 
    94 window-display-start returns the mark that points before the first
    95 character displayed in window.  Note that if window is the current
    96 window, then moving the start may not prove much, since recentering
    97 may move it back to approximately where it was originally.
    98 window-display-end is similar, but points after the last character
    99 displayed.  Moving the end is meaningless, since redisplay always
    100 moves it to after the last character.
    101 
    102 window-display-recentering window [Function]
    103 
    104 This function returns whether redisplay will ensure the buffer's point
    105 of window's buffer is visible after redisplay. This is setf-able, and
    106 changing window's buffer sets this to nil via Window Buffer Hook.
    107 
    108 window-point window [Function]
    109 
    110 This function returns as a mark the position in the buffer where the
    111 cursor is displayed.  This may be set with setf. If window is the current
    112 window, then setting the point will have little effect; it is forced
    113 to track the buffer point. When the window is not current, the window
    114 point is the position that the buffer point will be moved to when the
    115 window becomes current.
    116 
    117 center-window window mark [Function]
    118 
    119 This function attempts to adjust window's display start so the that
    120 markis vertically centered within the window.
    121 
    122 scroll-window window n [Function]
    123 
    124 This function scrolls the window down n display lines; if n is
    125 negative scroll up.  Leave the cursor at the same text position unless
    126 we scroll it off the screen, in which case the cursor is moved to the
    127 end of the window closest to its old position.
    128 
    129 displayed-p mark window [Function]
    130 
    131 Returns t if either the character before or the character after mark
    132 is being displayed inwindow, or nil otherwise.
    133 
    134 window-height window [Function]
    135 
    136 window-width window [Function]
    137 
    138 Height or width of the area of the window used for displaying the
    139 buffer, in character positions.  These values may be changed with
    140 setf, but the setting attempt may fail, in which case nothing is done.
    141 
    142 next-window window [Function]
    143 
    144 previous-window window [Function]
    145 
    146 Return the next or previous window of window. The exact meaning of
    147 next and previous depends on the device displaying the window.  It
    148 should be possible to cycle through all the windows displayed on a
    149 device using either next or previous (implying that these functions
    150 wrap around.)
    151 
    152 == 10.4. Cursor Positions ==
    153 
    154 A cursor position is an absolute position within a window's coordinate
    155 system.  The origin is in the upper-left-hand corner and the unit is
    156 character positions.
    157 
    158 mark-to-cursorpos mark window [Function]
    159 
    160 Returns as multiple values the X and Y position on which mark is being
    161 displayed in window, or nil if it is not within the bounds displayed.
    162 
    163 cursorpos-to-mark X Y window [Function]
    164 
    165 Returns as a mark the text position which corresponds to the given (X,
    166 Y) position within window, or nil if that position does not correspond
    167 to any text within window.
    168 
    169 last-key-event-cursorpos [Function]
    170 
    171 Interprets mouse input.  It returns as multiple values the (X, Y)
    172 position and the window where the pointing device was the last time
    173 some key event happened. If the information is unavailable, this
    174 returns nil.
     39== 10.4. Cursor Positions ==#CursorPositions
    17540
    17641mark-column mark [Function]
     
    18045takes into consideration strange characters such as tabs.
    18146
    182 move-to-column mark column &optional line [Function]
     47`move-to-column` mark column &optional line [Function]
    18348
    18449This function is analogous to move-to-position (page 5), except that
    185 it moves markto the position on line which corresponds to the
    186 specified column. Line defaults to the line that mark is currently on.
    187 If the line would not reach to the specified column, then nil is
     50it moves mark to the position on line which corresponds to the
     51specified column.  If the line would not reach to the specified column, then nil is
    18852returned and mark is not modified.  Note that since a character may be
    18953displayed on more than one column on the screen, several different
    19054values of column may cause mark to be moved to the same position.
    19155
    192 show-mark mark window time [Function]
     56== 10.5. Redisplay ==#Redisplay
    19357
    194 This function highlights the position of mark within window for time
    195 seconds, possibly by moving the cursor there. The wait may be aborted
    196 if there is pending input.  If mark is positioned outside the text
    197 displayed by window, then this returns nil, otherwise t.
     58The display of the buffer contents on the screen is updated at the
     59end of each command.  The following function can be used to control
     60the scroll position of the buffer in the view.
    19861
    199 == 10.5. Redisplay ==
     62`set-scroll-position` how &optional what [Function]
    20063
    201 Redisplay translates changes in the internal representation of text
    202 into changes on the screen.  Ideally this process finds the minimal
    203 transformation to make the screen correspond to the text in order to
    204 maximize the speed of redisplay.
     64Normally, after a command that changes the contents of the buffer
     65or the selection (i.e. the active region), the event handler repositions
     66the view so that the selection is visible, scrolling the buffer as
     67necessary.  Calling this function tells the system to not do that,
     68and instead to position the buffer in a particular way.  `how` can
     69be one of the following:
    20570
    206 redisplay [Function]
     71 :center-selection:: This causes the selection (or the point) to be centered in the visible area.  `what` is ignored.
     72 
     73 :page-up:: This causes the previous page of the buffer to be shown `what` is ignored.
    20774
    208 Redisplay Hook [Hemlock Variable]
     75 :page-down:: This causes the next page of the buffer to be shown. `what` is ignored.
    20976
    210 redisplay executes the redisplay process, and Hemlock typically
    211 invokes this whenever it looks for input. The redisplay process
    212 frequently checks for input, and if it detects any, it aborts. The
    213 return value is interpreted as follows:
     77 :lines-up::  This causes `what` previous lines to be scrolled in at the top. `what` must be an integer. 
    21478
    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.
     79 :lines-down:: This causes `what` next lines to be scrolled in at the bottom. `what` must be an integer.
    21880
    219 This function invokes the functions in Redisplay Hook on the current
    220 window after computing screen transformations but before executing
    221 them.  After invoking the hook, this recomputes the redisplay and then
    222 executes it on the current window.
     81 :line::  This causes the line containing `what` to be scrolled to the top of the view. `what` must be a mark.
    22382
    224 For the current window and any window with window-display-recentering
    225 set, redisplay ensures the buffer's point for the window's buffer is
    226 visible after redisplay.
    22783
    228 redisplay-all [Function]
    22984
    230 This causes all editor windows to be completely redisplayed.  For the
    231 current window and any window with window-display-recentering set, this
    232 ensures the buffer's point for the window's buffer is visible after
    233 redisplay.  The return values are the same as for redisplay, except
    234 that nil is never returned.
    23585
    236 editor-finish-output window [Function]
    237 
    238 This makes sure the editor is synchronized with respect to redisplay
    239 output towindow. This may do nothing on some devices.
    240 
     86[HemlockProgrammer Back to Table of Contents]