717519 - Make offline mode scriptable

Status: RESOLVED FIXED

(Camino Graveyard :: OS Integration, defect)

Description

[Smokey Ardisson (offline for a while; not following bugs - do not email)]

Attachment: Scripting support for offline mode

Chris wanted a script today that wasn't hard too hard to write with peeja's bookmarks support, but the very first item of his pseudo-code was: while (not Offline) {

That part sucked.  Because online state/offline mode was not scriptable, I had to resort to GUI Scripting.  Because GUI Scripting isn't on by default, I had to add a dozen-plus lines of goop to first check GUI Scripting state.  Then, because it's GUI Scripting, you hit bug 448992, which means you couldn't use the script as a toolbar script.

It made me angry.

Luckily, it was indeed as easy to implement script access to the offline/online state as I thought (I only had one dumb mistake and one thing I didn't know to do!).

Even better, it was then trivial to make online state change scriptable, because I could piggyback on some existing methods!

So, we now have read/right access to the application's online state.

Question: all our code deals with "offline", because "offline mode" that is a special state that we have to do stuff in order to enter.  The way we've made our menu item ("Work Offline") also reflects that, to some extent (but it was also because the Fx checkmark had bad menu text and seemed confusing). 

OTOH, it seems like, from a script-user perspective, it makes more sense to have "online" be the property name.  Dunno.

I thought back in the old days, some apps supported an state property for this, but the old MacScripter dictionary archive seems to be no more, and Uncle Google couldn't find any references to current or former applications that supported such a thing, as a clue to what others might use.

(Similarly, I have no idea if we might be stomping on some other 4char code.)

Lisa, as our resident scripting guru, can you weigh in on what you think the property name should be?

Chris, aside from the wacky KVC stuff, can you glance over the code?

tell application "Camino"
  online
end tell

tell application "Camino"
    set online to true
end tell

Comment 1

[Smokey Ardisson (offline for a while; not following bugs - do not email)]

Oh, bleh.

I just realized that that IBAction is a toggle, so it's not going to do the right thing.  I wrote a complex initial script to test it (the kind you'd use when testing the state in your scripts), and that masked the problem :/

So I'll have to think about how to re-implement write access.

Er, wait, probably the easiest way is to just test if (new state == current state) and do nothing, and only call toggleOfflineMode: when they differ.  That may not be the cleanest way, but it doesn't require lots of refactoring of the online code in MainController :P

I'll respin the patch tomorrow; too late now for sane patch-writing.

Comment 2

[Lisa Thompson]

I'm not sure I can offer anything compelling.

I do know a program that had a read/write boolean property for online/offline status -- Microsoft Entourage called it "working offline". I believe the corresponding menu item was called "Work Offline", but I can't remember whether, when set, it took a checkmark or toggled to something like "Go Online". It's possible that plain ol' "offline" was used as a value elsewhere in the dictionary, or maybe they wanted some consistency with the menu item name and thought the present participle was more grammatically correct. 

Sounds kind of awkward in hindsight, and I don't think I'd regard it as a worthy precedent to outweigh the simplicity of using just "online" or "offline". As for choosing between those two, maybe try writing the dictionary entry and see if one lends itself to clarity more than the other? Since my desktop is always online and I don't have a laptop, I'm not actually familiar with how Camino tracks online/offline status. So I'm not sure if it's appropriate to refer to the system status or just to Camino's setting.

offline (boolean) : Is Camino set to work offline?
online (boolean) : Whether the system currently has an online connection.

Presumably you wanted feedback of a more practical nature, but that's all I got. :-) I think either way, scripters will find it fairly straightforward.

Comment 3

[Smokey Ardisson (offline for a while; not following bugs - do not email)]

Er, I meant to post this yesterday afternoon, but apparently I never did :-(

--

Thanks, Lisa; that's helpful.

In the current .sdef, I wrote what Script Editor reports as

online (boolean) : Is the application online?

to match frontmost:

frontmost (boolean, r/o) : Is this the frontmost (active) application?

(I think, since it's not a standard cross-app property, we might want to consider making it say "Camino", but OTOH, "offline" sits right in between "name" and "frontmost" and "version", all of which use "the application" instead of the app name.  I guess we can control where it sits, though.)

Offline mode is a two-headed beast; Gecko can take itself offline when it detects no network connection at the OS level, or the user can choose to take Camino offline via our menu item.  But either way it's really an indication of Camino's state, not necessarily the system state.

Other phrasings all seem plausible to me, either with "Camino" or "the application"; there are more options for offline, though:

* offline : Is Camino in offline mode?
* offline : Is Camino working offline?
* offline : Is Camino offline?
* online : Is Camino online? (the current one)

--

What I don't like as much about "offline" is that it's a double negative:

if offline is false then do_stuff

vs 

if online is true then do_stuff

Chris got me copies of the .sdefs from a couple of Entourage versions from his vast network of connections, and the app's "working offline" property was "wkOf".  

As Lisa suspected, though, there are a couple of "online" properties, too:
* "allow online access" ("aOnA") (r/w) for POP accounts
* "online status" ("onSt") (r-o) for messages

Comment 4

[Smokey Ardisson (offline for a while; not following bugs - do not email)]

Attachment: Scripting support for offline mode, v1.1

Here's the updated patch I mentioned in comment 1 that makes sure we don't toggle when the desired state matches the current state.

I'm still on the fence about the property name and description.

Comment 5

[Smokey Ardisson (offline for a while; not following bugs - do not email)]

Comment on attachment 589766 [details] [diff] [review]
Scripting support for offline mode, v1.1

This one really is ready for review, as-is; I haven't had any eureka moments with it this weekend.

If you have an opinion on the property name or description, I'm open.

Comment 6

[Stuart Morgan]

Comment on attachment 589766 [details] [diff] [review]
Scripting support for offline mode, v1.1

>+  if (mOffline)
>+    return NO;
>+
>+  return YES;

Also known as:
  return !mOffline;

>+  // Because toggleOfflineMode: is a toggle, check to see if the desired state
>+  // is the same as the application's current state and bail.

The code is self-explanatory, so I would remove this comment.

sr=smorgan with those changes
(I'd lean slightly 'toward offline' FWIW, since that's the exceptional case, but not so much that I think we should repaint the bike shed.)

Comment 7

[Smokey Ardisson (offline for a while; not following bugs - do not email)]

http://hg.mozilla.org/camino/rev/bc0070c701ed with return !mOffline; and the comment deleted.

Comment 8

[Smokey Ardisson (offline for a while; not following bugs - do not email)]

Attachment: AppleScript

Here's an AppleScript that exercises this property.