In deriving a new snip class, these methods must be overridden to create a useful snip:

• get-extent

• draw

• copy

• resize if the snip can be resized by the user

• partial-offset if the snip can contain more than one item

• split if the snip can contain more than one item

• size-cache-invalid if the snip caches the result to get-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.

Default implementation: Returns #f.

The drawing context and snip’s locations in drawing context coordinates are provided.

Called when the snip’s editor’s method is called, recursive? is not #f, and this snip owns the caret.

Called when the snip’s editor’s method is called, recursive? is not #f, and this snip owns the caret.

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. When draw-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 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), and it is normally in a refresh (see Editors and Threads).

Default implementation: Draws nothing.

Default implementation: Calls the other-equal-to? method of snip (to simulate multi-method dispatch) in case snip provides a more specific equivalence comparison.

Default implementation: Returns (eq-hash-code a-snip).

Default implementation: Returns 1.

Default implementation: Returns 0.

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.

• '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 — an invisible snip that the user doesn’t see, such as a newline

• 'hard-newline — a newline must follow the snip

• '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 when it has the keyboard focus

• 'handles-all-mouse-events — this snip can handle mouse events that touch the snip or that immediately follow an event that touches the snip, even if the snip does not have the keyboard focus (see also on-goodbye-event)

• '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

Default implementation: Returns 1.

Default implementation: Returns 0.0.

Since this method returns the snip class stored by set-snipclass, it is not meant to be overridden.

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 "".

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.

Default implementation: Returns #t if the snip and a-snip are from the same class and have the same length.

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.

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.)

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 event get-x).

See also 'handles-events in get-flags.

Default implementation: Does nothing.

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 event get-x).

See also 'handles-events in get-flags.

Default implementation: Does nothing.

This method is called only when the snip has the 'handles-all-mouse-events flag set (see get-flags and set-flags).

Default implementation: Calls this object’s on-event method

Added in version 1.1 of package snip-lib.

The own-it? argument is #t if the snip owns the keyboard focus or #f otherwise.

Default implementation: Does nothing.

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.

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.

See also on-interactive-resize in pasteboard%.

Default implementation: Returns #f.

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).

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.

Default implementation: Sets the snip flags and notifies the snip’s editor that its flags have changed.

This method stores the snip class internally; other editor objects may access the snip class directly, instead of through the get-snipclass method.

The snip’s style may be changed by the system without calling this method.

Default implementation: Does nothing.

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.

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 with 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.