set-object-automatic-resize Function

Summary

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

Package

capi

Signature

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

Arguments

Description

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:

• If width-ratio, height-ratio and aspect-ratio are all set, the new width is the width of pinboard multiplied by width-ratio, and then modified as described below.
• If width-ratio is set and either height-ratio or aspect-ratio is not set, the new width is the width of pinboard multiplied by width-ratio.
• If width-ratio is not set, and both height-ratio and aspect-ratio are set, the new width is the new height divided by aspect-ratio.
• Otherwise, the new width is the same as the old width.

The new height of object is calculated as follows:

• If width-ratio and aspect-ratio are set, the new height is the new width multiplied by the aspect ratio. Note that if height-ratio is set, the new width will depend on height-ratio too.
• If height-ratio is set and either width-ratio or aspect-ratio are not set, the new height is the height of pinboard multiplied by height-ratio.
• If height-ratio is not set, but both width-ratio and aspect-ratio are set, the new height is the new width multiplied by aspect-ratio.
• Otherwise, the new height is the same as the old height.

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:

• If x-ratio is set, the new x coordinate is the sum of x-ratio multiplied by the width of pinboard plus x-offset, otherwise it is simply x-offset.
• The actual value of the x coordinate for object is adjusted according to the value of x-align such that the left, center or right of object align with the new coordinate.

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.

Notes

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.

Examples

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:

(set-object-automatic-resize 
 object
 :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:

(set-object-automatic-resize 
 object
 :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

manipulate-pinboard
static-layout
pinboard-object
simple-pane