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

object

A pinboard-object or a simple-pane.

x-align

nil, :left, :center or :right.

y-align

nil, :top, :center or :bottom.

x-offset

A real number, default value 0.

y-offset

A real number, default value 0.

x-ratio

A positive real number or nil.

y-ratio

A positive real number or nil.

width-ratio

A positive real number or nil.

height-ratio

A positive real number or nil.

aspect-ratio

A positive real number, t or nil.

aspect-ratio-y-weight

A real number, default value 0.5.

pinboard

A static-layout, if supplied. This argument is deprecated, and can always be omitted.

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.

Example

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