Today we cover the major API change in the way Pollock talks to and about pane bounds and rectangles.
Disruptive Change
Sometimes it is just impossible to make a change without possibly disrupting existing code. One of the reasons that Pollock isn't in production yet is that we believe that many APIs are not yet final. Thus, people using Pollock are on notice that sometimes big changes may still occur.
Fortunately, The changes and refactorings we've been talking about the last few months here, and that are in the current public release, are hopefully among the last of the major disruptive changes. In fact, except for one final big change in the guts of how what are currently called ComponentPairs (and a renaming of them), that is scheduled for early next year, Pollock is from now on about final features and bug fixes.
A Rose By Any Other Name
There used to be this whole visibleRectangle, displayableRectangle API, that was at best, poorly named and even more poorly understood except by me. So, there has been a huge renaming and the result is this.
So, #visibleRectangle and #displayableRectangle have been renamed to bounds and innerBounds respectively. #visibleBounds and #displayableBounds are gone. Here are the details of the new API on the Frames.
#bounds
#innnerBounds
A Frame's bounds area is that area the widget occupies in it's enclosing pane. A Frame's inner bounds is the area, possibly clipped, in which subpanes of the widget may display themselves. A case in point is a TextEdit which has a vertical scrollbar. The bounds is the total real estate of the widget, while the inner bounds is that area inside the TextEdit where text is allowed to be displayed (and clipped by any edge decoration or the scrollbar's bounds).
From a Pane, Artist or Agent, you can use the following sugar methods:
frameBounds
frameInnerBounds
In the guts of the Frame, another change has occurred:
This is the size of any border plus interior decoration. It is made up of two other values:
A Border's edgeRectangle : The size of any border (or zero if none)
An InteriorrDecoration's edgeRectangle : The size of any interior decoration
This value is used to determine how much to clip the visible area of a pane to compensate for any border and/or interior decoration. Another way to look at this is a pane's inner bounds is the bounds "minus" the decoration edge area. The Rectangle is degenerate, in that it describes left, right, top & bottom the amount to "insetBy:" the "bounds" of a Frame in order to describe it's innerBounds, and does not describe a rectangle directly usable.
This value and the API associated with it used to be much more complex, with a bunch of silly ways of setting it which, some, did little or nothing of value.
Events for Bounds
The next change was adding two new events to all panes:
#boundsChanging:
#boundsChanged:
These are triggered when the actual bounds of a pane is changed in an open window.
When a window is resized, any panes, no matter how deeply nested, that is affected by that change, will trigger #boundsChanged: after the change has taken place, and passes the new bounds as a parameter. It is important to note that if a resize of the window does not affect the actual bounds of a pane (such as an OriginExtent pane not dependent on any other enclosing pane) the #boundsChanged: event will not trigger.
When panes are "moved" or adjusted by a resizing splitter, both a before the fact #boundsChanging: event will occur, as well as a #boundsChanged: event after the fact.
When a pane's frame is programmatically changed when a window is open, such as the origin of an OriginExtent frame, the offset or fraction of a FractionalFrame or the edge alignment of an AlignmentFrame, both a before the fact #boundsChanging: event will occur, as well as a #boundsChanged: event after the fact.
There is not vetoable "aboutToChange" event. Consider these events as being notifications only.
You may notice the one imbalance in the events for window resize events. I really don't want to get into all the details, but believe me when I say I looked into trying to do some kind of general #boundsChanging for panes, but the fact is it's a bit of a Heisenberg issue. That said, the Window itself DOES trigger a
#boundsChanging: before it changes, so, at least we have that... It's just the subpanes on a resize we can't know about.
New FractionalFrame Creation Methods
As part of his work, Vassili has added a number of helper creation methods to FractionalFrame:
leftFraction:offset:rightFraction:offset:topFraction:offset:bottomFraction:offset:
leftFraction:offset:topFraction:offset:rightFraction:offset:bottomFraction:offset:
These are just a couple of "Do All At Once" methods
above: <aNumber>
Create a fractional frame positioned above <aNumber> fraction (e.g. if aNumber is 0.5, in the top half of the parent frame).
below: <aNumber>
Create a fractional frame positioned below <aNumber> fraction (e.g. if aNumber is 0.5, in the bottom half of the parent frame).
leftOf: <aNumber>
Create a fractional frame positioned to the left of <aNumber> fraction (e.g. if aNumber is 0.5, in the left half of the parent frame).
leftOf: <aNumber> top: <topOffset> bottom: <bottomOffset>
Create a fractional frame positioned to the left of <aNumber> fraction (e.g. if aNumber is 0.5, in the left half of the parent frame)
and having a fixed height between the two given offsets.
rightOf: <aNumber>
Create a fractional frame positioned to the right of <aNumber> fraction (e.g. if aNumber is 0.5, in the right half of the parent frame).
rightOf: <aNumber> top: <topOffset> bottom: <bottomOffset>
Create a fractional frame positioned to the right of <aNumber> fraction (e.g. if aNumber is 0.5, in the right half of the parent frame)
and having a fixed height between the two given offsets.
New API : #preferredExtent
We have added a simple api to all panes, named #preferredExtent. Given any pane (or window) you can send #preferredExtent to it, and it will answer the minimum area that this pane wants in order to be visible in a window.
The pane doesn't have to be opened, or even added to a window. It figures out this value based on all it can know.
For instance, given an empty TextEdit, it will answer the size of the border of the TextEdit. Turn on scrollbars on that empty TextEdit, it will now answer a larger number that includes the area needed to also see the scrollbars. Add text to the TextEdit, and it will measure the text, and give you the size it takes to see all of the text, plus the scrollbars (which in the result, would be disabled).
Now, if we put this TextEdit in a Form or Window, and give that TextEdit a frame of some kind, we then take this frame into consideration also, even though the Form or Window itself may not yet be "open".
The purpose of this api is to allow tools or users to be able to take a bunch of panes, cobble them together in any number of ways, and then by asking for the #preferredExtent, possibly figure out an appropriate optimal layout for these panes.
One important clarification: a frame is taken into consideration when computing the preferredExtent of the *container* of the framed widget, not of the widget itself.
To continue the above example, suppose preferredExtent of the TextEdit is 500@2000, and you give it a Fractional Frame with all fractions 0, left and top offset 10, and bottom and right offset 100. This means the TextEdit will occupy the rectangle (10@10 corner: 100@100) in its containing Form or Window.
Now if you send #preferredExtent to the containing Form or Window, it will answer 100@100 (assuming there are no other widgets in it). If you send #preferredExtent to the TextEdit, the answer will still be 500@2000.
It's all really that simple... to explain at least. Behind the scenes it has been discussed and designed and re-designed and re-discussed over the period of several months... And even now there is one bit we may revisit in the near future with regard to RelationalFrames.
One More
Next week we'll outline the last of the changes that is seen in the public release of Pollock... Adding actions to Menus.
Previous Topic
