Add API for focusing OSX tabs

[trishume]

macOS Sierra added the ability to use tabs with any document-based app.
Unfortunately for some apps like Sublime Text, there's no way by default
to use keyboard shortcuts to switch between these tabs.

This adds an API for doing so.

[codecov]

Codecov Report

Merging #1513 into master will decrease coverage by 0.05%.
The diff coverage is 0%.

@@            Coverage Diff            @@
##           master   #1513      +/-   ##
=========================================
- Coverage   23.66%   23.6%   -0.06%     
=========================================
  Files         129     129              
  Lines       23979   24030      +51     
  Branches     2842    2856      +14     
=========================================
- Hits         5674    5672       -2     
- Misses      17939   17992      +53     
  Partials      366     366

[asmagill]

Is there a reason you're using a double here? Since you immediately put it into a CFIndex and don't use indexDouble again, it's probably cleaner to use luaL_checkinteger and assign it directly to tabIndex.

[asmagill]

Unclear meaning here -- in lua any number, including 0 is considered "true"

[trishume]

This was a copy-paste mistake.

[asmagill]

wrong return description; per tag line description should probably read "true if the tab was successfully pressed, or false if there was a problem" or similar

[trishume]

Copy paste mistake, fixed.

[asmagill]

See above line comments. Also, how hard would it be to add a method which returns an integer specifying the number of tabs in a given window?

[trishume]

I addressed all comments and added a method for counting tabs, and tested it.

Interestingly, I tested it and this method of finding and switching tabs also finds Chrome and Safari tabs.

[asmagill]

lgtm; @cmsj and @trishume a point to consider before merging:

The tabs are indexed starting at 0; Lua and most of the extensions we've added use 1 as the starting point -- in fact in a lot of the methods we've added we specifically add/subtract 1 when interfacing with the macOS APIs to keep Hammerspoon's indexing consistent with the Lua conventions since this is what most users know/see/interact with. If these methods were adding string or table like functionality or acted in a string or table like manner, I would recommend doing the same here; since it's not, I don't have strong feelings one way or the other, but I will say it took me by surprise when I tested this on my own machine and I had to re-read the documentation to make sure this was known/expected behavior.

Thoughts? I'm fine either way, but I did want to pose the question before merging.

[trishume]

Cool, I wondered about that, knowing that there are other APIs that use 1-based indices makes it easy. I just changed it to use 1-based indexing. And that lets me remove the - 1 in my config where I bind it to alt+1-9.

[asmagill]

@trishume do you consider this complete or do you have additional plans?
@cmsj, if complete, objections to merging?

[trishume]

I consider this complete. I don't plan on adding anything else, at least for now.

[asmagill]

@trishume -- I hadn't thought about this until just now, so consider it a future feature request if you don't have time right now, but any idea on how hard it might be to add a method to determine what tab is currently focused in a window and another to get the names(title) of all of the tabs in a window?

If you tell me you don't have the time right now or that you don't know how long it might take to add, I'll merge this now; on the other hand if you agree with the usefulness of these methods and think you can get these added shortly, I'll hold off.

[trishume]

I'm unlikely to work on those methods myself. I don't think they'd be too hard, but they're not trivial like the tab count one. They also wouldn't be useful to me personally. Although I can see the current tab index being useful to others for a "next/previous tab" binding, and the names being useful in combo with hs.chooser.

[asmagill]

Understood, I may tackle them myself at some point then as I've worked with the accessibility API myself before, but figured I'd bounce it off of you since you've done so more recently.

Merging as is then.