Provides a rectangular area in a pinboard-layout with drawing capabilities.
ellipse
item-pinboard-object
image-pinboard-object
line-pinboard-object
drawn-pinboard-object
rectangle
The output pane on which the pinboard object is drawn.
If t, the pinboard object is made active.
A plist of Graphics Ports drawing options.
The following initargs are geometry hints, influencing the initial size and position of a pinboard-object:
The x position of the pinboard object in the pinboard.
The y position of the pinboard object in the pinboard.
The minimum width of the pinboard object in the pinboard.
The minimum height of the pinboard object in the pinboard.
The maximum width of the pinboard object in the pinboard.
The maximum height of the pinboard object in the pinboard.
The minimum visible width of the pinboard object.
The minimum visible height of the pinboard object.
The maximum visible width of the pinboard object.
The maximum height of the pinboard object.
The minimum width of the display region.
The minimum height of the display region.
The class pinboard-object provides a rectangular area in a pinboard-layout with drawing and highlighting capabilities. A pinboard object behaves just like a simple pane within layouts, meaning that they can be placed into rows, columns and other layouts, and that they size themselves in the same way. The main distinction is that a pinboard object is a much smaller object than a simple pane as it does not need to create a native window for itself.
Each pinboard object is placed into a pinboard layout (or into a layout itself inside a pinboard layout), and then when the pinboard layout wishes to redisplay a region of itself, it calls the function draw-pinboard-object on each of the pinboard objects that are contained in that region (in the order that they are specified as children to the layout).
The graphics-args slot allows drawing options to be set. These include the font , the background and foreground colors, and others (see graphics-state). The graphics-args are used by the built-in pinboard-object (all subclasses of pinboard-object except drawn-pinboard-object) as extra arguments in calls to drawing functions. For example, to create a filled red rectangle object, you can use:
(make-instance
'capi:rectangle
:filled t :x 100 :y 100
:visible-min-width 100
:visible-min-height 100
:graphics-args '(:foreground :red))
The graphics args can be accessed after creation using pinboard-object-graphics-args, and it is also possible to modify a single value using pinboard-object-graphics-arg.
When
no-highlight
is t, CAPI does not call draw-pinboard-object-highlighted even when the object is highlighted. Typically, the drawing function you supply (either the method draw-pinboard-object or the
display-callback
for drawn-pinboard-object) will do the highlight in this case, using pinboard-object-highlighted-p to check if they need to.
The geometry hints are interpreted as described for element. After creation, you can query the geometry of a pinboard-object using the functions static-layout-child-position and static-layout-child-size and static-layout-child-geometry. You can also set the geometry using cl:setf with these functions.
By default a pinboard-object does not accept the input focus.
There are a number of predefined pinboard objects provided by the CAPI. They are as follows:
Draws an ellipse.
Draws a rectangle.
right-angle-line-pinboard-object
Uses a user-defined display function.
The main user of pinboard objects in the CAPI is the graph pane, which uses item-pinboard-object and line-pinboard-object to display its nodes and edges respectively.
To force a pinboard object to redraw itself call redraw-pinboard-object. The redrawing may be cached and displayed at a later date.
Call the generic functions highlight-pinboard-object and unhighlight-pinboard-object to highlight a pinboard and remove its highlighting. If you want non-standard highlighting, you can implement methods for your subclass of pinboard-object.
You can test whether a whether a point or region coincides with a pinboard object by the generic functions over-pinboard-object-p and pinboard-object-overlap-p. The default methods assume a rectangle based on the geometry, which must always be the enclosing rectangle of the whole pinboard object. Therefore you only need to implement methods if your subclass of pinboard-object has a non-rectangular shape.
automatic-resize makes the pinboard object resize automatically. This has an effect only if it is placed inside a static-layout (including subclasses like pinboard-layout). The effect is that when the static-layout is resized then the pinboard object also changes its geometry.
The value of automatic-resize defines how the pinboard object's geometry changes. It must be a plist of keywords and values which match the keywords of the function set-object-automatic-resize and are interpreted in the same way.
You can also control automatic resizing of a pinboard object using set-object-automatic-resize.
(example-edit-file "capi/graphics/pinboard-test")
(example-edit-file "capi/graphics/highlight-rectangle-pinboard")
(example-edit-file "capi/graphics/circled-graph-nodes")
There are further examples in Self-contained examples.
pinboard-layout
draw-pinboard-object
graph-pane
highlight-pinboard-object
over-pinboard-object-p
redraw-pinboard-object
redraw-pinboard-layout
pinboard-object-overlap-p
pinboard-object-graphics-arg
set-object-automatic-resize
static-layout
unhighlight-pinboard-object
Laying Out CAPI Panes
Creating graphical objects
CAPI User Guide and Reference Manual (Macintosh version) - 3 Aug 2017