Class

Summary

The class pinboard-layout provides two very useful pieces of functionality for displaying CAPI windows. Firstly it is a subclass of static-layout and so it allows its children to be positioned anywhere within itself (like a pinboard). Secondly it supports pinboard-objects which are rectangular areas within the layout which have size and drawing functionality.

Package

capi

Superclasses

output-pane
static-layout

Subclasses

simple-pinboard-layout

Initargs

:highlight-style

A keyword.

Description

When a pinboard-layout lays out its children, it positions them at the x and y specified as hints (using :x and :y), and sizes them to their minimum size (which can be specified using :visible-min-width and :visible-max-width). Objects can be moved and resized inside the pinboard-layout using (setf pinboard-pane-position) and (setf pinboard-pane-size). You can find which object is the top object at a point by using pinboard-object-at-position.

By default, the pinboard-layout is made sufficiently large to accommodate all of its children, as specified by fit-size-to-children in the superclass static-layout. Note that this results in the pinboard resizing itself automatically when objects are added, removed, moved or resized. If the layout has scrollbars these are also affected. If you need the sizing capabilities, then use the class simple-pinboard-layout which surrounds a single child, and adopts the size constraints of that child.

The pinboard layout handles the display of pinboard objects itself by calculating which objects are visible in the region that needs redrawing, and then by calling the generic function draw-pinboard-object on these objects in the order that they are specified in the layout description. This means that if two pinboard objects overlap, the later one in the layout description will be on top of the other one. In other words, the description defines the Z-order for objects of type pinboard-object. (See the note below regarding the Z-order for objects of type simple-pane.)

The children of the pinboard-layout are defined by its description (inherited from layout). When the contents of the layout need to be manipulated while it is on the screen, it is possible to do this by using (setf layout-description). However, when the change involves only pinboard-objects, it is much more efficient to use manipulate-pinboard instead. This will also cause less flickering.

Highlighting of the layout's children by highlight-pinboard-object is controlled by the value of highlight-style , as follows:

:invert

Swaps the foreground and background colors.

:standard

Uses system colors.

:default

Calls draw-pinboard-object-highlighted.

The default value of highlight-style is :default.

record-dependent-object can be used to record objects that need to be cleaned-up when the pinboard layout is destroyed.

Notes

1. The output-pane initarg :drawing-mode controls quality of drawing in a pinboard-layout, including anti-aliasing of any text displayed on Microsoft Windows and GTK+.
2. If redrawing flickers on Microsoft Windows or Motif, perhaps because there are many pinboard objects, you can pass the output-pane initarg :draw-with-buffer t, which uses a pixmap to buffer the output before drawing it to the screen. See output-pane for more information.
3. pinboard-layout defines its own default display-callback (see output-pane), pinboard-layout-display. If you want to do additional drawing, see pinboard-layout-display.
4. Objects of type simple-pane are drawn directly by the windowing system and cannot be clipped relative to pinboard-objects, which are drawn by CAPI. Therefore simple-panes always appear on top in a pinboard, and their position in the description does not affect the Z-order.

Example

Here are some examples of the use of pinboard objects with pinboard layouts.

(capi:contain 

 (make-instance

  'capi:pinboard-layout

  :description 

  (list

   (make-instance

    'capi:image-pinboard-object

    :image 

    (example-file "capi/graphics/Setup.bmp")

    :x 20 :y 20)))

 :best-width 540 :best-height 415)

(capi:contain 

 (make-instance

  'capi:pinboard-layout

  :description (list

                (make-instance

                 'capi:item-pinboard-object

                 :text "Hello"

                 :x 40 :y 10)

                (make-instance

                 'capi:line-pinboard-object

                 :x 10 :y 30

                 :visible-min-width 100)))

                :best-width 200 :best-height 200)

There are further examples here:

(example-edit-file "capi/applications/")

and here:

(example-edit-file "capi/graphics/")

This example illustrates use of draw-with-buffer t:

(example-edit-file "capi/graphics/compositing-mode")

This example shows how to draw a rectangle as the user moves the mouse to select pinboard objects:

(example-edit-file "capi/graphics/highlight-rectangle-pinboard")

There are further examples in Self-contained examples.

See also

Creating graphical objects
manipulate-pinboard
output-pane
pinboard-object
pinboard-object-at-position
pinboard-pane-position
pinboard-pane-size
record-dependent-object
redraw-pinboard-object
static-layout
CAPI elements
Tooltips for output panes