snip-admin% : class?

superclass: object%

See Administrators for information about the role of administrators. The snip-admin% class is never instantiated directly. It is not even instantiated through derived classes by most programmers; each text% or pasteboard% object creates its own administrator. However, it may be useful to derive a new instance of this class to display snips in a new context. Also, it may be useful to call the methods of an existing administrator from an owned snip.

To create a new snip-admin% class, all methods described here must be overridden. They are all invoked by the administrator’s snip.

Because a snip-admin% object typically owns more than one snip, many methods require a snip% object as an argument.

(make-object snip-admin%) → (is-a?/c snip-admin%)

Creates a (useless) editor administrator.

(send a-snip-admin get-dc) → (or/c (is-a?/c dc<%>) false/c)

Gets a drawing context suitable for determining display size information. If the snip is not displayed, #f is returned.

(send a-snip-admin get-editor)

→ (or/c (is-a?/c text%) (is-a?/c pasteboard%))

Returns the editor that this administrator reports to (directly or indirectly).

(send a-snip-admin get-view x y w h [snip]) → void?

x : (or/c (box/c real?) false/c)

y : (or/c (box/c real?) false/c)

w : (or/c (box/c (and/c real? (not/c negative?))) false/c)

h : (or/c (box/c (and/c real? (not/c negative?))) false/c)

snip : (or/c (is-a?/c snip%) false/c) = #f

Specification: Gets the location and size of the visible region of a snip in snip coordinates. The result is undefined if the given snip is not managed by this administrator.

If snip is not #f, the current visible region of the snip is installed in the boxes x, y, w, and h. The x and y values are relative to the snip’s top-left corner. The w and h values may be larger than the snip itself.

If snip is #f, the total visible region of the snip’s top-level display is returned in editor coordinates. Using #f for snip is analogous to using #t for full? in get-view in editor-admin%.

If no snip is specified, then the location and size of the snip’s editor are returned, instead, in editor coordinates.

See also get-view in editor-admin%.

Default implementation: Fills all boxes with 0.0.

(send a-snip-admin get-view-size h w) → void?

h : (or/c (box/c (and/c real? (not/c negative?))) false/c)

w : (or/c (box/c (and/c real? (not/c negative?))) false/c)

Specification: Gets the visible size of the administrator’s display region.

If the display is an editor canvas, see also reflow-container.

Default implementation: Fills all boxes with 0.0.

(send a-snip-admin modified snip modified?) → void?

snip : (is-a?/c snip%)

modified? : any/c

Specification: Called by a snip to report that its modification state has changed to either modified or unmodified.

Default implementation: Does nothing.

(send a-snip-admin needs-update   snip             localx             localy             w             h)   →   void?

snip : (is-a?/c snip%)

localx : real?

localy : real?

w : (and/c real? (not/c negative?))

h : (and/c real? (not/c negative?))

Specification: Called by the snip to request that the snip’s display needs to be updated. The administrator determines when to actually update the snip; the snip’s draw method is eventually called.

The localx, localy, w, and h arguments specify a region of the snip to be refreshed (in snip coordinates).

No update occurs if the given snip is not managed by this administrator.

Default implementation: Does nothing.

(send a-snip-admin popup-menu menu snip x y) → boolean?

menu : (is-a?/c popup-menu%)

snip : (is-a?/c snip%)

x : real?

y : real?

Specification: Opens a popup menu in the display for this snip’s editor. The result is #t if the popup succeeds, #f otherwise (independent of whether the user selects an item in the popup menu).

The menu is placed at x and y in snip coordinates.

While the menu is popped up, its target is set to the top-level editor in the display for this snip’s editor. See get-popup-target for more information.

Default implementation: Returns #f.

(send a-snip-admin recounted snip refresh?) → void?

snip : (is-a?/c snip%)

refresh? : any/c

Specification: Called by a snip to notify the administrator that the specified snip has changed its count. The snip generally needs to be updated after changing its count, but the snip decides whether the update should occur immediately.

If refresh? is not #f, then the snip is requesting to be updated immediately. Otherwise, needs-update must eventually be called as well.

The method call is ignored if the given snip is not managed by this administrator.

Default implementation: Does nothing.

(send a-snip-admin release-snip snip) → boolean?

snip : (is-a?/c snip%)

Specification: Requests that the specified snip be released. If this administrator is not the snip’s owner or if the snip cannot be released, then #f is returned. Otherwise, #t is returned and the snip is no longer owned.

See also release-snip in editor<%> .

The result is #f if the given snip is not managed by this administrator.

Default implementation: Returns #f.

(send a-snip-admin resized snip refresh?) → void?

snip : (is-a?/c snip%)

refresh? : any/c

Specification: Called by a snip to notify the administrator that the specified snip has changed its display size. The snip generally needs to be updated after a resize, but the snip decides whether the update should occur immediately.

If refresh? is not #f, then the snip is requesting to be updated immediately, as if calling needs-update. Otherwise, needs-update must eventually be called as well.

The method call is ignored if the given snip is not managed by this administrator.

Default implementation: Does nothing.

(send a-snip-admin scroll-to   snip             localx             localy             w             h             refresh?            [ bias])   →   boolean?

snip : (is-a?/c snip%)

localx : real?

localy : real?

w : (and/c real? (not/c negative?))

h : (and/c real? (not/c negative?))

refresh? : any/c

bias : (one-of/c 'start 'end 'none) = 'none

Specification: Called by the snip to request scrolling so that the given region is visible. The snip generally needs to be updated after a scroll, but the snip decides whether the update should occur immediately.

The localx, localy, w, and h arguments specify a region of the snip to be made visible by the scroll (in snip coordinates).

If refresh? is not #f, then the editor is requesting to be updated immediately.

The bias argument is one of:

• 'start – if the range doesn’t fit in the visible area, show the top-left region

• 'none – no special scrolling instructions

• 'end – if the range doesn’t fit in the visible area, show the bottom-right region

The result is #t if the editor is scrolled, #f otherwise.

The method call is ignored (and the result is #f) if the given snip is not managed by this administrator.

Default implementation: Returns #f.

(send a-snip-admin set-caret-owner   snip             domain)   →   void?

snip : (is-a?/c snip%)

domain : (one-of/c 'immediate 'display 'global)

Specification: Requests that the keyboard focus is assigned to the specified snip. If the request is granted, the own-caret method of the snip is called.

See set-caret-owner for information about the possible values of domain.

The method call is ignored if the given snip is not managed by this administrator.

Default implementation: Does nothing.

(send a-snip-admin update-cursor) → void?

Specification: Queues an update for the cursor in the display for this snip’s editor. The actual cursor used will be determined by calling the snip’s adjust-cursor method as appropriate.

Default implementation: Does nothing.