snip% : class?
superclass: object%
extends: equal<%>
A direct instance ofsnip%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:
• get-extent
• draw
• copy
• resizeif the snip can be resized by the user
• partial-offsetif the snip can contain more than one item
• splitif the snip can contain more than one item
• size-cache-invalidif the snip caches the result toget-extent
• get-text(not required)
• find-scroll-step,get-num-scroll-steps, andget-scroll-step-offsetif the snip can contain more than one scroll position
• set-unmodifiedif the snip’s internal state can be modified by the user, and call modifiedin 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 theread method. Export the snip-class%instance assnip-class from a module, and use a classname of the form"(lib ...)"as described in §5.2.1.1 “Snip Classes”.
• For each instance of the snip class, set the snip’s class object withset-snipclass.
• Override thecopymethod.
• Override thewritemethod.
To define a class of snips that read specially withopen-input-text-editor:
• Make yoursnip%class implementreadable-snip<%>.
• Implement theread-specialmethod.
(new snip%) → (is-a?/c snip%)
Creates a plain snip of length 1 with the"Basic"style ofthe-style-list. (send a-snip adjust-cursor dc
xy editorx editory event)
→ (or/c (is-a?/c cursor%) #f) dc : (is-a?/c dc<%>)
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#fis returned, a default cursor is selected by the editor. (See adjust-cursorineditor<%>for more information.)
Default implementation:Returns#f.
(send a-snip blink-caret dc x y) → void?
dc : (is-a?/c dc<%>) 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.
(send a-snip can-do-edit-operation? op
[recursive?]) → boolean?
op :
(or/c 'undo 'redo 'clear 'cut 'copy 'paste 'kill 'select-all
'insert-text-box 'insert-pasteboard-box 'insert-image)
recursive? : any/c = #t
Seecan-do-edit-operation?ineditor<%>.
Called when the snip’s editor’s method is called,recursive?is not#f, and this snip owns the caret.
(send a-snip copy) → (is-a?/c snip%)
Creates and returns a copy of this snip. The copymethod is responsible for copying this snip’s style (as returned byget-style) to the new snip.
(send a-snip do-edit-operation op
[recursive?
time]) → void?
op :
(or/c 'undo 'redo 'clear 'cut 'copy 'paste 'kill 'select-all
'insert-text-box 'insert-pasteboard-box 'insert-image)
recursive? : any/c = #t time : exact-integer? = 0
Seedo-edit-operationineditor<%>.
Called when the snip’s editor’s method is called,recursive?is not#f, and this snip owns the caret.
(send a-snip draw dc xy lefttop right bottom dxdy
draw-caret) → void?
dc : (is-a?/c dc<%>) x : real?
y : real?
left : real?
top : real?
right : real?
bottom : real?
dx : real?
dy : real?
draw-caret :
(or/c 'no-caret 'show-inactive-caret 'show-caret (cons/c exact-nonnegative-integer?
exact-nonnegative-integer?))
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 argumentsleft,top,right, andbottomdefine a clipping region (in DC coordinates) that the snip can use to optimize drawing, but it can also ignore these arguments.
The dx anddy argument provide numbers that can be subtracted fromx andy to obtain the snip’s location in editor coordinates (as opposed to DC coordinates, which are used for drawing).
See §5.5 “Caret Ownership” for information aboutdraw-caret. Whendraw-caret is a pair, refrain from drawing a background for the selected region, and if (get-highlight-text-color)returns a color (instead of#f), use that color for drawing selected text and other selected foreground elements.
Before this method is called, the font, text color, and pen color for the snip’s style will have
been set in the drawing context. (The drawing context is not so configured forget-extent or partial-offset.) Thedrawmethod must not make any other assumptions about the state of the drawing context, except that the clipping region is already set to something appropriate. Beforedrawreturns, it must restore any drawing context settings that it changes.
See alsoon-paintineditor<%>.
The snip’s editor is usually internally locked for writing and reflowing when this method is called (see also §5.8 “Internal Editor Locks”).
Default implementation:Draws nothing.
(send a-snip equal-to? snip equal?) → boolean?
snip : (is-a?/c snip%)
equal? : (-> any/c any/c boolean?)
Specification:Seeequal<%>.
Default implementation: Calls theother-equal-to?method ofsnip (to simulate multi-method dispatch) in casesnip provides a more specific equivalence comparison.
(send a-snip other-equal-to? that equal?) → boolean?
that : (is-a?/c snip%)
equal? : (-> any/c any/c boolean?)
Default implementation:Returns(eq? a-snip that).
(send a-snip equal-hash-code-of hash-code) → exact-integer?
hash-code : (any/c . -> . exact-integer?)
Specification:Seeequal<%>.
Default implementation:Returns(eq-hash-code a-snip). (send a-snip equal-secondary-hash-code-of hash-code)
→ exact-integer?
hash-code : (any/c . -> . exact-integer?)
Specification:Seeequal<%>. Default implementation:Returns1.
(send a-snip find-scroll-step y) → exact-nonnegative-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:Returns0.
(send a-snip get-admin) → (or/c (is-a?/c snip-admin%) #f)
Returns the administrator for this snip. (The administrator can be #feven 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).
(send a-snip get-extent dc xy [w
hdescent space lspace
rspace]) → void?
dc : (is-a?/c dc<%>) x : real?
y : real?
w : (or/c (box/c (and/c real? (not/c negative?))) #f) = #f h : (or/c (box/c (and/c real? (not/c negative?))) #f) = #f descent : (or/c (box/c (and/c real? (not/c negative?))) #f)
= #f
space : (or/c (box/c (and/c real? (not/c negative?))) #f) = #f lspace : (or/c (box/c (and/c real? (not/c negative?))) #f)
= #f
rspace : (or/c (box/c (and/c real? (not/c negative?))) #f)
= #f
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 horizon-tal spaces (amount of width which is “filler” space at the left and right). Those values are returned by filling thew,h,descent,space,lspace, andrspace 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, useget-snip-locationineditor<%>.
A drawing context is provided for the purpose of finding font sizes, but no drawing should occur. Theget-extentandpartial-offsetmethods 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