Returns true if object is an output record, otherwise returns false. [annotate] |
The protocol class that is used to indicate that an object is a displayed output record, that is, an object that represents a visible piece of output on some output stream. This is a subclass of bounding-rectangle. If you want to create a new class that behaves like a displayed output record, it should be a subclass of displayed-output-record. All instantiable subclasses of displayed-output-record must obey the displayed output record protocol. [annotate] Note: The text doesn't say that displayed-output-record is a subclass of output-record
but surely, that must be the case. It wouldn't hurt to mention it explicitly. [edit]-- Robert Strandh 2007-01-02 06:09Z Note: That doesn't seem to be necessarily the case: at least on Franz's CLIM 2, they're disjoint types.
[edit]-- Estevan Castilho 2023-10-01 13:56Z Note: Indeed, Franz CLIM imposes the following:
- output-record implements output record protocol
- displayed-output-record is a leaf and does not implement it [edit]-- Daniel Kochmanski 2023-10-26 09:50Z All displayed output records are mutable. [annotate] |
Returns true if object is a displayed output record, otherwise returns false. [annotate] |
All subclasses of either output-record or displayed-output-record must handle these three initargs, which are used to specify, respectively, the x and y position of the output record, and the parent of the output record. [annotate] |
All subclasses of output-record must handle the :size initarg. It is used to specify how much room should be left for child output records (if, for example, the children are stored in a vector). It is permissible for :size to be ignored, provided that the resulting output record is able to store the specified number of child output records. [annotate] |
All subclasses of output-record and displayed-output-record must inherit or implement methods for the following generic functions. [annotate]
When the generic functions in this section take both record and a stream arguments, CLIM implementations will specialize the stream argument for the standard-output-recording-stream class and the record argument for all of the implementation-specific output record classes. [annotate]
Returns the x and y position of the output record record as two rational numbers. The position of an output record is the position of the upper-left corner of its bounding rectangle. The position is relative to the stream, where (0,0) is (initially) the upper-left corner of the stream. [annotate] |
Changes the x and y position of the output record record to be x and y (which are rational numbers), and updates the bounding rectangle to reflect the new position (and saved cursor positions, if the output record stores it). If record has any children, all of the children (and their descendants as well) will be moved by the same amount as record was moved. The bounding rectangles of all of record's ancestors will also be updated to be large enough to contain record. This does not replay the output record, but the next time the output record is replayed it will appear at the new position. [annotate] For CLIM implementations that do not support setf*, the "setter" function for this is output-record-set-position. [annotate] |
Returns the x and y starting cursor position of the output record record as two integer values. The positions are relative to the stream, where (0,0) is (initially) the upper-left corner of the stream. [annotate] Text output records and updating output records maintain the cursor position. Graphical output records and other output records that do not require or affect the cursor position will return nil as both of the values. [annotate] |
Changes the x and y starting cursor position of the output record record to be x and y (which are integers). This does not affect the bounding rectangle of record, nor does it replay the output record. For those output records that do not require or affect the cursor position, the method for this function is a no-op. [annotate] For CLIM implementations that do not support setf*, the "setter" function for this is output-record-set-start-cursor-position. [annotate] |
Returns the x and y ending cursor position of the output record record as two integer values. The positions are relative to the stream, where (0,0) is (initially) the upper-left corner of the stream. Graphical output records do not track the cursor position, so only text output record (and some others) will return meaningful values for this. [annotate] Text output records and updating output records maintain the cursor position. Graphical output records and other output records that do not require or affect the cursor position will return nil as both of the values. [annotate] |
Changes the x and y ending cursor position of the output record record to be x and y (which are integers). This does not affect the bounding rectangle of record, nor does it replay the output record. For those output records that do not require or affect the cursor position, the method for this function is a no-op. [annotate] For CLIM implementations that do not support setf*, the "setter" function for this is output-record-set-end-cursor-position. [annotate] |
Returns the output record that is the parent of the output record record, or nil if the record has no parent. [annotate] |
This function bind stream-recording-p of stream to false, and then calls replay-output-record on the arguments record, stream, and region. If stream-drawing-p of stream is false, replay does nothing. replay is typically called during scrolling, by repaint handlers, and so on. [annotate] CLIM implementations are permitted to default region either to nil or to the region corresponding to viewport of stream. [annotate] Note: [Free-CLIM] This function arranges for replay-output-record to be called eventually and perhaps asynchronously from within the event loop of the port. [edit]-- Gilbert Baumann 2022-01-24 22:46Z |
Displays the output captured by the output record record on the output recording stream stream, exactly as it was originally captured (subject to subsequent modifications). The current user transformation, line style, text style, ink, and clipping region of stream are all ignored during the replay operation. Instead, these are gotten from the output record. [annotate] If record is not a displayed output record, then replaying it involves replaying all of its children. If record is a displayed output record, then replaying it involves redoing the graphics operation captured in the record. [annotate] region is a region that can be supplied to limit what records are displayed. Only those records that overlap region are replayed. The default for region is +everywhere+. [annotate] It is permissible for implementations to restrict replay-output-record such that stream must be the same stream on which the output records were originally recorded. [annotate] Minor issue: How does replaying a text output record (or any record that maintains the cursor position) affect the cursor position of the stream? It is probably that case that replay should not affect the cursor position. --- SWM [annotate] Note: x-offset and y-offset are implementation quirks. In "classic" CLIM they should be bound to the output-record parent's absolute coordinates (because inner output record coordinates are relative to its parent). McCLIM (as of 2019-08-07) ignores these parameters. Franz CLIM User Guide suggests that they were to be removed. [edit]-- Daniel Kochmanski 2019-08-07 08:47Z Note: [Free-CLIM] We keep output record coordinates relative to the parent and thus use the x-offset and y-offset arguments. That is not a quirk, but necessary to make moving output records an O(1) operation. replay-output-record is not for the "user" to call. There is replay which would get the x-offset and y-offset arguments for you. [edit]-- Gilbert Baumann 2022-01-24 22:23Z |
This method is used to establish the usual "effective size" of record for hit detection queries. Four values are returned corresponding to the edges of the bounding rectangle that is the hit detection rectangle. The default method (on CLIM's standard output record class) is equivalent to calling calling bounding-rectangle* on record, but this method can be specialized to return a larger bounding rectangle in order to implement a form of hysteresis. [annotate] |
This is used to definitively answer hit detection queries, that is, determining that the point (x,y) is contained within the output record record. Once the position (x,y) has been determined to lie within output-record-hit-detection-rectangle*, output-record-refined-sensitivity-test is invoked. Output record subclasses can provide a method that provides a more precise definition of a hit, for example, output records for elliptical rings will implement a method that detects whether the pointing device is on the elliptical ring. [annotate] Note: Surely, the reference to output-record-refined-sensitivity-test should rather
be a reference to output-record-refined-position-test, no? [edit]-- Robert Strandh 2008-08-13 13:08Z |
This method is called in order to draw a highlighting box around the output record record on the output recording stream stream. state will be either :highlight (meaning to draw the highlighting) or :unhighlight (meaning to erase the highlighting). The default method (on CLIM's standard output record class) will simply draw a rectangle that corresponds the the bounding rectangle of record. [annotate] |
Returns the ink used by the displayed output record displayed-output-record. [annotate] |
All classes that are subclasses of output-record must implement methods for the following generic functions. [annotate]
Returns a sequence of all of the children of the output record record. It is unspecified whether the sequence is a freshly created object or a "live" object representing the state of record. [annotate] |
Adds the new output record child to the output record record. The bounding rectangle for record (and all its ancestors) must be updated to account for the new child record. [annotate] Note: It wouldn't hurt to mention here that the order of insertion is important.
When output records are replayed, it is done in the order that they were
inserted. [edit]-- Robert Strandh 2007-01-02 06:22Z The methods for the add-output-record will typically specialize only the record argument. [annotate] |
Removes the output record child from the output record record. The bounding rectangle for record (and all its ancestors) may be updated to account for the child having been removed, although this is not mandatory. [annotate] If errorp is true (the default) and child is not contained within record, then an error is signalled. [annotate] The methods for the delete-output-record will typically specialize only the record argument. [annotate] |
Removes all of the children from the output record record, and resets the bounding rectangle of record to its initial state. [annotate] |
Returns the number of children contained within the output record record. [annotate] |
function record x y &optional x-offset y-offset &rest function-args [annotate] Maps over all of the children of the output record record that contain the point at (x,y), calling function on each one. function is a function of one or more arguments, the first argument being the record containing the point; it has dynamic extent. function is also called with all of function-args as "apply" arguments. [annotate] If there are multiple records that contain the point and that overlap each other, map-over-output-records-containing-position must hit the uppermost (most recently inserted) record first and the bottommost (least recently inserted) record last. Otherwise, the order in which the records are traversed is unspecified. [annotate] |
function record region &optional x-offset y-offset &rest function-args [annotate] Maps over all of the children of the output record record that overlap the region region, calling function on each one. function is a function of one or more arguments, the first argument being the record overlapping the region; it has dynamic extent. function is also called with all of function-args as "apply" arguments. [annotate] If there are multiple records that overlap the region and that overlap each other, map-over-output-records-overlapping-region must hit the bottommost (least recently inserted) record first and the uppermost (most recently inserted) record last. Otherwise, the order in which the records are traversed is unspecified. [annotate] |
The following functions are called by programmers and by CLIM itself in order to notify a parent output record when the bounding rectangle of one of its child output record changes. [annotate]
This function is called whenever a new child is added to an output record. Its contract is to update the bounding rectangle of the output record record to be large enough to completely contain the new child output record child. The parent of record must be notified by calling recompute-extent-for-changed-child. [annotate] add-output-record is required to call recompute-extent-for-new-child. [annotate] |
| recompute-extent-for-changed-child | record child old-min-x old-min-y old-max-x old-max-y | [Generic Function] |
This function is called whenever the bounding rectangle of one of the childs of a record has been changed. Its contract is to update the bounding rectangle of the output record record to be large enough to completely contain the new bounding rectangle of the child output record child. All of the ancestors of record must be notified by recursively calling recompute-extent-for-changed-child. [annotate] Whenever the bounding rectangle of an output record is changed or delete-output-record is called, recompute-extent-for-changed-child must be called to inform the parent of the record that a change has taken place. [annotate] Note: This contradicts the description of delete-output-record where calling recompute-extent-for-changed-child is optional. Or is this mandated from the application programmer? [edit]-- Gilbert Baumann 2006-03-03 22:43Z |
This function is called whenever the bounding rectangles of a number of children of a record have been changed, such as happens during table and graph formatting. Its contract is to compute the bounding rectangle large enough to contain all of the children of the output record record, adjust the bounding rectangle of the output record record accordingly, and then call recompute-extent-for-changed-child on record. [annotate] |