All Manuals > CAPI User Guide and Reference Manual > 21 CAPI Reference Entries

set-object-automatic-resize Function


Controls automatic resizing and repositioning of objects in a static layout.




set-object-automatic-resize object &key x-align y-align x-offset y-offset x-ratio y-ratio width-ratio height-ratio aspect-ratio aspect-ratio-y-weight pinboard

nil, :left, :center or :right.
nil, :top, :center or :bottom.
A real number, default value 0.
A real number, default value 0.
A positive real number or nil.
A positive real number or nil.
A positive real number or nil.
A positive real number or nil.
A positive real number, t or nil.
A real number, default value 0.5.
A static-layout, if supplied. This argument is deprecated, and can always be omitted.

The function set-object-automatic-resize arranges for object to be resized and/or re-positioned automatically when pinboard is resized, or removes such a setting.

The value of aspect-ratio can be t, which means use the current aspect ratio of object (that is, its height divided by its width).

object should be either a pinboard-object or a simple-pane which is (or will be) displayed in a static-layout. This object will be added to the description of the layout by one of its :description initarg, (setf capi:layout-description) or manipulate-pinboard.

pinboard is the layout for object. If pinboard is already displayed with object in its description, the argument pinboard can be omitted.

When pinboard is resized, object is resized if either height-ratio or width-ratio are set.

The new width of object is calculated as follows:

The new height of object is calculated as follows:

If all of width-ratio, height-ratio and aspect-ratio are set, the new width and height of object are calculated as follows:

  1. Compute calculated-width as the width of pinboard multiplied by width-ratio, and calculated-height as the height of pinboard multiplied by height-ratio.
  2. Compute aspect-ratio-ratio as:
    (/ (/ calculated-height calculated-width) aspect-ratio)
  3. Compute correction as:
    (expt aspect-ratio-ratio aspect-ratio-y-weight)
  4. Compute the new width as calculated-width multiplied by correction, and the new height as the new width multiplied by aspect-ratio.

The result is that if aspect-ratio-y-weight is 0, correction is 1 and height-ratio is effectively ignored, while if aspect-ratio-y-weight is 1, correction cancels the effect of width-ratio. With the default value of 0.5, the resulting position is in the (geometric) middle, and object takes a fixed fraction of the area of the pinboard.

After resizing (if needed), object is also positioned horizontally if x-align is non-nil, and vertically if y-align is non-nil.

The new x coordinate of object is calculated as follows:

The new y coordinate of object is calculated similarly, using y-ratio and y-offset, with an adjustment such that the top, center or bottom of object aligns with the new coordinate according to y-align.

If all of width-ratio, height-ratio, x-align and y-align are nil, automatic resizing/re-positioning of object is removed.

set-object-automatic-resize can be called before object is actually displayed, and its effect persists over calls adding and removing object to/from static-layouts. The effect of set-object-automatic-resize also persists if object is removed and added again, either to the same layout or another layout.

Repeated calls to set-object-automatic-resize set only the values that are passed to set-object-automatic-resize. Keys that are not passed are left with their previous value. A call that removes the automatic resizing (because width-ratio, height-ratio, x-align and y-align are all nil) erases all the values.

set-object-automatic-resize returns t if the object is set up for automatic resizing, or nil if the object is set up for no automatic resizing.

  1. The initarg :automatic-resize can be used to set up automatic resizing in the call to make-instance.
  2. The name set-object-automatic-resize is slightly inaccurate, because this function can alter an object's position without actually changing its size.
Compatibility note

In LispWorks 6.0 the effect of set-object-automatic-resize does not persist if the object is removed and then added, to any layout.

In LispWorks 6.0 each call to set-object-automatic-resize sets all the values.


Put an object of fixed size at the top right corner:

(set-object-automatic-resize object 
                             :x-ratio 1 :x-align :right)

Put an object in the bottom-right quadrant:

 :x-ratio 0.5 :y-ratio 0.5
 :width-ratio 0.5 :height-ratio 0.5)

Put an object with a fixed aspect ratio and object width linear with the width of the layout in the center:

 :x-align :center :y-align :center
 :x-ratio 0.5 :y-ratio 0.5
 :aspect-ratio 0.6 :width-ratio 0.1)

There is a further example in:

(example-edit-file "capi/layouts/automatic-resize")
See also


CAPI User Guide and Reference Manual (Macintosh version) - 01 Dec 2021 19:31:27