Next: , Previous: Unit Protocol, Up: Protocols

18.4.6 Redisplay Protocol

A buffer can be on display in several panes, possibly by being located in several Drei instances. Thus, the buffer does not concern itself with redisplay, but assumes that its host Drei instance will redisplay when appropriate. There is no predictable definitive rule for when a Drei will be redisplayed, but when it is, it will be done by calling the following generic function.

— Generic Function: display-drei frame drei

Drei must be an object of type drei and frame must be a CLIM frame containing the editor pane of drei. If you define a new subclass of drei, you must define a method for this generic function. In most cases, methods defined on this function will merely be a trampoline to a function specific to the given Drei.

The redisplay engine supports syntax-specific customization of the display in order to facilitate such functionality as syntax highlighting. This is done through the following two generic functions, both of which have sensible default methods defined by the Fundamental syntax, so if your syntax is a subclass of fundamental-syntax, you do not need to define them.

— Generic Function: drei:display-drei-contents stream drei syntax

The purpose of this function is to display the buffer contents of a Drei instance to some output surface. stream is the CLIM output stream that redisplay should be performed on, drei is the Drei instance that is being redisplayed, and syntax is the syntax object of the buffer in drei. Methods defined for this generic function can draw whatever they want, but they should not assume that they are the only user of stream, unless the stream argument has been specialized to some application-specific pane class that can guarantee this. For example, when accepting multiple values using the accepting-values macro, several Drei instances will be displayed simultaneously on the same stream. It is permitted to only specialise stream on clim-stream-pane and not extended-output-stream. When writing methods for this function, be aware that you cannot assume that the buffer will contain only characters, and that any subsequence of the buffer is coercable to a string. Drei buffers can contain arbitrary objects, and redisplay methods are required to handle this (though they are not required to handle it nicely, they can just ignore the object, or display the princed representation.)

— Generic Function: drei:display-drei-cursor stream drei cursor syntax

The purpose of this function is to display a visible indication of a cursor of a Drei instance to some output surface. stream is the CLIM output stream that drawing should be performed on, drei is the Drei instance that is being redisplayed, cursor is the cursor object to be displayed (a subclass of drei-cursor) and syntax is the syntax object of the buffer in drei}. Methods on this generic function can draw whatever they want, but they should not assume that they are the only user of stream, unless the stream argument has been specialized to some application-specific pane class that can guarantee this. It is permitted to only specialise stream on clim-stream-pane and not extended-output-stream. It is recommended to use the function offset-to-screen-position to determine where to draw the visual representation for the cursor. It is also recommended to use the ink specified by cursor to perform the drawing, if applicable. This method will only be called by the Drei redisplay engine when the cursor is active and the buffer position it refers to is on display - therefore, offset-to-screen-position is *guaranteed* to not return NIL or t.