Share via

Help us Name the Adorner "Placement" APIs

  • Article

Looking back to my most recent article on adorners you'll recall that we had this API on AdornerPanel that allowed the Control Developer to specify where and with what size their design time adorners were positioned on the design surface:

AdornerPanel.SetHorizontalStretch(_slider, AdornerStretch.Stretch);
AdornerPanel.SetVerticalStretch(_slider, AdornerStretch.None);
AdornerPanel.SetTargetSizeFactor(_slider, new Vector(1.0, 0));
AdornerPanel.SetAdornerSizeFactor(_slider, new Vector(0, 1.0));
AdornerPanel.SetAdornerOriginFactor(_slider, new Vector(0, -1.0));
AdornerPanel.SetAdornerOriginOffset(_slider, new Vector(0, -3));

This API set was actually restrictive in ways that we need to overcome so Richard Bailey took a crack at redesigning these APIs.  His first post on this is here and his second post is here. 

As Richard mentions on his blog, we are looking for feedback on how to name the following classes (the following text is lifted directly from his blog):

Contribution Group
This is a collection of class instances that declare adjustments to the adorner size and position.

Adorner Space
The adorner space properties allow you to adjust the size off the adorner based on the desired size determined by the style size of the adorner.  Adorner position can be adjusted relative to the final computed size fo the adorner.  Size and position can also be adjusted in pixels.  Adorner space does nto scale when the designer zooms in/out.

SizeRelativeToAdornerDesiredHeight(relativeTo, factor, offset)
SizeRelativeToAdornerDesiredWidth(relativeTo, factor, offset)
PositionRelativeToAdornerHeight(relativeTo, factor, offset)
PositionRelativeToAdornerWidth(relativeTo, factor, offset)

Render Space
The render space properties allow you to adjust the size or position of the adorner relative to the adorned element and by an offset measured in pixels in thatcoordinate system.  Render space size and positions adjustments are affected by and transform that affects the render size and shape of the adorned element.

SizeRelativeToContentRenderHeight(relativeTo, factor, offset)
SizeRelativeToContentRenderWidth(relativeTo, factor, offset)
PositionRelativeToContentRenderHeight(relativeTo, factor, offset)
PositionRelativeToContentRenderWidth(relativeTo, factor, offset)

Layout Space
The layout space properties allow you to adjust the size or position of the adorner relative to the layout slot fo the adorned element and an offset measured in pixels of that coordinate system.  Layout space size and positions are afected by transforms that affect the render space of the adorned element parent.

SizeRelativeToContentLayoutHeight(relativeTo, factor, offset)
SizeRelativeToContentLayoutWidth(relativeTo, factor, offset)
PositionAtContentLayoutSlot(relativeTo )
PositionRelativeToContentLayoutHeight(relativeTo, factor, offset)
PositionRelativeToContentLayoutWidth(relativeTo, factor, offset)

Example
An example of using these APIs for a grab handle that is positioned on the top right of the selected element (also stolen from Richards post):

ContributionGroup placement = new ContributionGroup();
placement.Add(new SizeRelativeToAdornerDesiredWidth(this, 1.0, 0));
placement.Add(new SizeRelativeToAdornerDesiredHeight(this, 1.0, 0));
placement.Add(new PositionAtContentLayoutSlot(null));
placement.Add(new PositionRelativeToContentLayoutWidth(null, 1.0, 0));
placement.Add(new PositionRelativeToAdornerWidth(this, 0, -3.0));
placement.Add(new PositionRelativeToAdornerHeight(this, -1.0, 3.0));
AdornerPanel.SetPlacement(this, placement);

Now before you panic, we do plan to have an API that is easier to approach that will wrap this API.  You will be able to use this simple API for the most common types of adorner layout, use the ContributionGroups and Size* & Position* classes to further customize your adorners layout and finally, you can define your own Contributions and terms to create your own layout management of your adorners.

Summary
We're looking for names to the following:

ContributionGroup
Contribution

SizeRelativeToAdornerDesiredHeight(relativeTo, factor, offset)
SizeRelativeToAdornerDesiredWidth(relativeTo, factor, offset)
PositionRelativeToAdornerHeight(relativeTo, factor, offset)
PositionRelativeToAdornerWidth(relativeTo, factor, offset)

SizeRelativeToContentRenderHeight(relativeTo, factor, offset)
SizeRelativeToContentRenderWidth(relativeTo, factor, offset)
PositionRelativeToContentRenderHeight(relativeTo, factor, offset)
PositionRelativeToContentRenderWidth(relativeTo, factor, offset)

SizeRelativeToContentLayoutHeight(relativeTo, factor, offset)
SizeRelativeToContentLayoutWidth(relativeTo, factor, offset)
PositionAtContentLayoutSlot(relativeTo )
PositionRelativeToContentLayoutHeight(relativeTo, factor, offset)
PositionRelativeToContentLayoutWidth(relativeTo, factor, offset)

Please post your suggestions as a comment.

Thanks for your help!