Expose frame and visibleFrame for Screen

[kasper]

Expose frame and visibleFrame for Screen to help position modals with the same origin based frame.

1. Rename Screen#frameInRectangle() to Screen#flippedFrame()
2. Rename Screen#visibleFrameInRectangle() to Screen#flippedVisibleFrame()
3. Deprecate Screen#frameInRectangle() for removal in later versions and alias it to Screen#flippedFrame()
4. Deprecate Screen#visibleFrameInRectangle() for removal in later versions and alias it to Screen#flippedVisibleFrame()
5. Expose Screen#frame()
6. Expose Screen#visibleFrame()

[mafredri]

I'm a bit confused as to when you should use which. Previously *frameInRectangle was the only thing available, and thus default. Now it feels like frame and visibleFrame should be the defaults (due to naming). How might this change affect how you calculate positions?

[kasper]

@mafredri This is why I originally was hesitant about exposing these (see #43). See a short description here: https://github.com/kasper/phoenix/blob/master/API.md#about-coordinates. Basically the lower level APIs use the flipped frame (the whole Accessibility API), higher level APIs (such as modals) use the “normal” frame. In most cases you will use the flipped frame, so no changes regarding this.

Eventually I decided to expose these, because it’s indeed a lot more easier to position modals correctly when you can get the frame with the same coordinate system. The “default” frame in this context should definitely be the flipped frame, but unfortunately you cannot override existing methods with category extensions for NSScreen. A reason why the previous functions had weird names — frameInRectangle and visibleFrameInRectangle. 😞

[kasper]

@mafredri Coordinate systems are hard. Let me know if you have any suggestions on how to improve this.

[mafredri]

Thanks for the explanation, I'll have a look at the API docs!

Regarding the issue of naming, how about switching them around in JavaScript? This seems to work for me, but I did not do a whole lot of testing (also, no idea what repercussions it might have 😝):

(function (s) {
    var _frame = s.frame;
    var _visibleFrame = s.visibleFrame;
    s.frame = s.flippedFrame;
    s.visibleFrame = s.flippedVisibleFrame;
    s.flippedFrame = _frame;
    s.flippedVisibleFrame = _visibleFrame;
})(Screen.prototype);

[kasper]

@mafredri Probably a bit risky. 😝 Anyway, the current naming follows Apple’s standard. The default coordinate system for Cocoa is bottom-left based, this is what frame and visibleFrame return for NSScreen.

Now, if you want to adjust the position of windows using the Accessibility API, you need to use a top-left based coordinate system. Brilliant! Apple refers to this as a flipped coordinate system. Basically the y-coordinate is adjusted. So this is why they are now called flippedFrame and flippedVisibleFrame.

Unfortunately I know that this is bound to be confusing to people who are not familiar with this. It’s a drawback and mostly a documentation dilemma.