superclass: object% |
A direct instance of snip% is uninteresting. Useful snips are defined by instantiating derived subclasses, but this class defines the basic functionality.
In deriving a new snip class, these methods must be overridden to create a useful snip:
resize if the snip can be resized by the user
partial-offset if the snip can contain more than one item
size-cache-invalid if the snip caches the result toget-extent
get-text (not required)
find-scroll-step, get-num-scroll-steps, and get-scroll-step-offset if the snip can contain more than one scroll position
set-unmodified if the snip’s internal state can be modified by the user, and call modified in the snip’s administrator when the state changes the first time
If a snip can contain more than one item, then the snip’s count must be maintained as well.
To define a class of snips that can be saved or cut-and-pasted:
Create an instance of snip-class%, implementing the read method. Export the snip-class% instance as snip-class from a module, and use a classname of the form "(lib ...)" as described in Snip Classes.
For each instance of the snip class, set the snip’s class object with set-snipclass.
Override the copy method.
Override the write method.
To define a class of snips that read specially with open-input-text-editor:
Make your snip% class implement readable-snip<%>.
Implement the read-special method.
(make-object snip%) → (is-a?/c snip%) |
Creates a plain snip of length 1 with the "Basic" style of the-style-list.
| ||||||||||||||||||||||||
x : real? | ||||||||||||||||||||||||
y : real? | ||||||||||||||||||||||||
editorx : real? | ||||||||||||||||||||||||
editory : real? | ||||||||||||||||||||||||
event : (is-a?/c mouse-event%) |
Specification: Called to determine the cursor image used when the cursor is moved over the snip in an editor. If #f is returned, a default cursor is selected by the editor. (See adjust-cursor in editor<%> for more information.)
Default implementation: Returns #f.
(send a-snip blink-caret dc x y) → void? |
x : real? |
y : real? |
Tells the snip to blink the selection caret. This method is called periodically when the snip’s editor’s display has the keyboard focus, and the snip has the editor-local focus.
The drawing context and snip’s locations in drawing context coordinates are provided.
| ||||||||||||||
| ||||||||||||||
recursive? : any/c = #t |
Refine this method with augment.
See can-do-edit-operation? in editor<%>.
Called when the snip’s editor’s method is called, recursive? is not #f, and this snip owns the caret.
Creates and returns a copy of this snip. The copy method is responsible for copying this snip’s style (as returned by get-style) to the new snip.
| |||||||||||||||||||||
| |||||||||||||||||||||
recursive? : any/c = #t | |||||||||||||||||||||
See do-edit-operation in editor<%>.
Called when the snip’s editor’s method is called, recursive? is not #f, and this snip owns the caret.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
x : real? | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
y : real? | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
left : real? | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
top : real? | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
right : real? | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bottom : real? | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
dx : real? | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
dy : real? | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
draw-caret : (one-of/c 'no-caret 'show-inactive-caret 'show-caret) |
Specification: Called (by an editor) to draw the snip into the given drawing context with the snip’s top left corner at location (x, y) in DC coordinates.
The arguments left, top, right, and bottom define a clipping region (in DC coordinates) that the snip can use to optimize drawing, but it can also ignore these arguments.
The dx and dy argument provide numbers that can be subtracted from x and y to obtain the snip’s location in editor coordinates (as opposed to DC coordinates, which are used for drawing).
See Caret Ownership for information about draw-caret.
Before this method is called, the correct font, text color, and pen color for the snip’s style will have been set in the drawing context already. (This is not true for get-extent or partial-offset.) The draw method must not make any other assumptions about the state of the drawing context, except that the clipping region is already set to something appropriate. Before draw returns, it must restore any drawing context settings that it changes.
See also on-paint in editor<%>.
The snip’s editor is usually internally locked for writing and reflowing when this method is called (see also Internal Editor Locks).
Default implementation: Draws nothing.
(send a-snip find-scroll-step y) → nonnegative-exact-integer? |
y : real? |
Specification: If a snip contains more than one vertical scroll step (see get-num-scroll-steps) then this method is called to find a scroll step offset for a given y-offset into the snip.
Default implementation: Returns 0.
(send a-snip get-admin) → (or/c (is-a?/c snip-admin%) false/c) |
Returns the administrator for this snip. (The administrator can be #f even if the snip is owned but not visible in the editor.)
(send a-snip get-count) → (integer-in 0 100000) |
Returns the snip’s count (i.e., number of items within the snip).
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
x : real? | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
y : real? | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Specification: Calculates the snip’s width, height, descent (amount of height which is drawn below the baseline), space (amount of height which is “filler” space at the top), and horizontal spaces (amount of width which is “filler” space at the left and right). Those values are returned by filling the w, h, descent, space, lspace, and rspace boxes.
This method is called by the snip’s administrator; it is not normally called directly by others. To get the extent of a snip, use get-snip-location in editor<%> .
A drawing context is provided for the purpose of finding font sizes, but no drawing should occur. The get-extent and partial-offset methods must not make any assumptions about the state of the drawing context, except that it is scaled properly. In particular, the font for the snip’s style is not automatically set in the drawing context before the method is called. (Many snips cache their size information, so automatically setting the font would be wasteful.) If get-extent or partial-offset changes the drawing context’s setting, it must restore them before returning. However, the methods should not need to change the drawing context; only font settings can affect measurement results from a device context, and get-text-extent in dc<%> accepts a font% argument for sizing that overrides that device context’s current font.
The snip’s left and top locations are provided as x and y in editor coordinates, in case the snip’s size depends on its location; the x and y arguments are usually ignored. In a text editor, the y-coordinate is the line’s top location; the snip’s actual top location is potentially undetermined until its height is known.
If a snip caches the result size for future replies, it should invalidate its cached size when size-cache-invalid is called (especially if the snip’s size depends on any device context properties).
If a snip’s size changes after receiving a call to get-extent and before receiving a call to size-cache-invalid, then the snip must notify its administrator of the size change, so that the administrator can recompute its derived size information. Notify the administrator of a size change by call its resized method.
The snip’s editor is usually internally locked for writing and reflowing when this method is called (see also Internal Editor Locks).
Default implementation: Fills in all boxes with 0.0.
Returns flags defining the behavior of the snip, a list of the following symbols:
'is-text – this is a text snip derived from string-snip%; do not set this flag
'can-append – this snip can be merged with another snip of the same type
'invisible – the user doesn’t “see” this snip; e.g.: a carriage return
'newline – a newline currently follows the snip; only an owning editor should set this flag
'handles-events – this snip can handle keyboard and mouse events
'width-depends-on-x – this snip’s display width depends on the snip’s x-location within the editor; e.g.: tab
'height-depends-on-y – this snip’s display height depends on the snip’s y-location within the editor
'width-depends-on-y – this snip’s display width depends on the snip’s y-location within the editor
'height-depends-on-x – this snip’s display height depends on the snip’s x-location within the editor
'uses-editor-path – this snip uses its editor’s pathname and should be notified when the name changes; notification is given as a redundant call to set-admin
(send a-snip get-num-scroll-steps) |
→ nonnegative-exact-integer? |
Specification: Returns the number of horizontal scroll steps within the snip. For most snips, this is 1. Embedded editor snips use this method so that scrolling in the owning editor will step through the lines in the embedded editor.
Default implementation: Returns 1.
(send a-snip get-scroll-step-offset offset) |
offset : nonnegative-exact-integer? |
Specification:If a snip contains more than one vertical scroll step (see get-num-scroll-steps) then this method is called to find the y-offset into the snip for a given scroll offset.
Default implementation: Returns 0.0.
(send a-snip get-snipclass) → (is-a?/c snip-class%) |
Returns the snip’s class, which is used for file saving and cut-and-paste.
Since this method returns the snip class stored by set-snipclass, it is not meant to be overridden.
Returns the snip’s style. See also set-style.
offset : nonnegative-exact-integer? |
num : nonnegative-exact-integer? |
flattened? : any/c = #f |
Specification: Returns the text for this snip starting with the position offset within the snip, and continuing for a total length of num items. If offset is greater than the snip’s count, then "" is returned. If num is greater than the snip’s count minus the offset, then text from the offset to the end of the snip is returned.
If flattened? is not #f, then flattened text is returned. See Flattened Text for a discussion of flattened vs. non-flattened text.
Default implementation: Returns "".
| ||||||||||||||||||||||||||||
buffer : mutable = string | ||||||||||||||||||||||||||||
offset : nonnegative-exact-integer? | ||||||||||||||||||||||||||||
num : nonnegative-exact-integer? | ||||||||||||||||||||||||||||
buffer-offset : nonnegative-exact-integer? |
Specification: Like get-text in non-flattened mode, except that the characters are put into the given mutable string, instead of returned in a newly allocated string.
The buffer string is filled starting at position buffer-offset. The buffer string must be at least num+buffer-offset characters long.
Default implementation: Calls get-text, except in the case of a string-snip%, in which case buffer is filled directly.
Returns #t if this snip has an owner, #f otherwise. Note that a snip may be owned by an editor if it was inserted and then deleted from the editor, if it’s still in the editor’s undo history.
Specification: Return #t if a-snip “matches” snip, #f otherwise.
Default implementation: Returns #t if the snip and a-snip are from the same class and have the same length.
(send a-snip merge-with prev) → (or/c (is-a?/c snip%) false/c) |
Specification: Merges a-snip with prev, returning #f if the snips cannot be merged or a new merged snip otherwise. This method will only be called if both snips are from the same class and both have the 'can-append flag.
If the returned snip does not have the expected count, its count is forcibly modified. If the returned snip is already owned by another administrator, a surrogate snip is created.
The snip’s editor is usually internally locked for reading when this method is called (see also Internal Editor Locks).
Default implementation: Returns #f.
Returns the next snip in the editor owning this snip, or #f if this is the last snip.
In a text editor, the next snip is the snip at the position following this snip’s (last) position. In a pasteboard, the next snip is the one immediately behind this snip. (See Editor Structure and Terminology for information about snip order in pasteboards.)
| ||||||||||||||||||||||||||||||||||||||||||
x : real? | ||||||||||||||||||||||||||||||||||||||||||
y : real? | ||||||||||||||||||||||||||||||||||||||||||
editorx : real? | ||||||||||||||||||||||||||||||||||||||||||
editory : real? | ||||||||||||||||||||||||||||||||||||||||||
event : (is-a?/c key-event%) |
Specification: Called to handle keyboard events when this snip has the keyboard focus and can handle events. The drawing context is provided, as well as the snip’s location in display coordinates (the event uses display coordinates), and the snip’s location in editor coordinates.
The x and y arguments are the snip’s location in display coordinates. The editorx and editory arguments are the snip’s location in editor coordinates. To get event’s x location in snip coordinates, subtract x from (send (scheme event) get-x).
See also 'handles-events in get-flags.
Default implementation: Does nothing.
| ||||||||||||||||||||||||||||||||||||||||||
x : real? | ||||||||||||||||||||||||||||||||||||||||||
y : real? | ||||||||||||||||||||||||||||||||||||||||||
editorx : real? | ||||||||||||||||||||||||||||||||||||||||||
editory : real? | ||||||||||||||||||||||||||||||||||||||||||
event : (is-a?/c mouse-event%) |
Specification: Called to handle mouse events on the snip when this snip can handle events and when the snip has the keyboard focus. See on-char for information about the arguments.
The x and y arguments are the snip’s location in display coordinates. The editorx and editory arguments are the snip’s location in editor coordinates. To get event’s x location in snip coordinates, subtract x from (send (scheme event) get-x).
See also 'handles-events in get-flags.
Default implementation: Does nothing.
own-it? : any/c |
Specification: Notifies the snip that it is or is not allowed to display the caret (indicating ownership of keyboard focus) in some display. This method is not called to request that the caret is actually shown or hidden; the draw method is called for all display requests.
The own-it? argument is #t if the snip owns the keyboard focus or #f otherwise.
Default implementation: Does nothing.
(send a-snip partial-offset dc x y len) → real? |
x : real? |
y : real? |
len : nonnegative-exact-integer? |
Specification: Calculates a partial width for the snip, starting from the first snip item and continuing for len items. The drawing context and snip’s locations in editor coordinates are provided. See also get-extent.
The snip’s editor is usually internally locked for writing and reflowing when this method is called (see also Internal Editor Locks).
Default implementation: Returns 0.0.
Returns the previous snip in the editor owning this snip, or #f if this is the first snip.
(send a-snip release-from-owner) → boolean? |
Specification: Asks the snip to try to release itself from its owner. If the snip is not owned or the release is successful, then #t is returned. Otherwise, #f is returned and the snip remains owned. See also is-owned?.
Use this method for moving a snip from one editor to another. This method notifies the snip’s owning editor that someone else really wants control of the snip. It is not necessary to use this method for "cleaning up" a snip when it is deleted from an editor.
Default implementation: Requests a low-level release from the snip’s owning administrator.
Specification: Resizes the snip. The snip can refuse to be resized by returning #f. Otherwise, the snip will resize (it must call its administrator’s resized method) and return #t.
See also on-interactive-resize in pasteboard%.
Default implementation: Returns #f.
admin : (or/c (is-a?/c snip-admin%) false/c) |
Sets the snip’s administrator. Only an administrator should call this method.
The default method sets the internal state of a snip to record its administrator. It will not modify this state if the snip is already owned by an administrator and the administrator has not blessed the transition. If the administrator state of a snip is not modified as expected during a sensitive call to this method by an instance of text% or pasteboard%, the internal state may be forcibly modified (if the new administrator was #f) or a surrogate snip may be created (if the snip was expected to receive a new administrator).
The snip’s (new) editor is usually internally locked for reading when this method is called (see also Internal Editor Locks).
c : (integer-in 1 100000) |
Specification: Sets the snip’s count (i.e., the number of items within the snip).
The snip’s count may be changed by the system (in extreme cases to maintain consistency) without calling this method.
Default implementation: Sets the snip’s count and notifies the snip’s administrator that the snip’s size has changed.
Specification: Sets the snip’s flags. See get-flags.
Default implementation: Sets the snip flags and notifies the snip’s editor that its flags have changed.
(send a-snip set-snipclass class) → void? |
class : (is-a?/c snip-class%) |
Sets the snip’s class, used for file saving and cut-and-paste.
This method stores the snip class internally; other editor objects may access the snip class directly, instead of through the get-snipclass method.
Sets the snip’s style if it is not owned by any editor. See also get-style and is-owned?.
The snip’s style may be changed by the system without calling this method.
(send a-snip set-unmodified) → void? |
Specification: Called by the snip’s administrator to notify the snip that its changed have been saved. The next time snip’s internal state is modified by the user, it should call modified to report the state change (but only on the first change after this method is called, or the first change after the snip acquires a new administrator).
Default implementation: Does nothing.
(send a-snip size-cache-invalid) → void? |
Specification: Called to notify the snip that it may need to recalculate its display arguments (width, height, etc.) when it is next asked, because the style or location of the snip has changed.
The snip’s (new) editor is usually internally locked for reflowing when this method is called (see also Internal Editor Locks).
Default implementation: Does nothing.
position : nonnegative-exact-integer? |
Specification:Splits the snip into two snips. This is called when a snip has more than one item and something is inserted between two items.
The arguments are a relative position integer and two boxes. The position integer specifies how many items should be given to the new first snip; the rest go to the new second snip. The two boxes must be filled with two new snips. (The old snip is no longer used, so it can be recycled as a new snip.)
If the returned snips do not have the expected counts, their counts are forcibly modified. If either returned snip is already owned by another administrator, a surrogate snip is created.
The snip’s editor is usually internally locked for reading when this method is called (see also Internal Editor Locks).
Default implementation: Creates a new snip% instance while position elements, and modifies a-snip to decrement its count by position. The nest snip is installed into first and a-snip is installed into second.
f : (is-a?/c editor-stream-out%) |
Writes the snip to the given stream. (Snip reading is handled by the snip class.) Style information about the snip (i.e., the content of get-style) will be saved and restored automatically.