Info about AEInteractWithUser

Shane,

I started out to find out more about AEInteractWithUser. The first thing I discovered is carbon is like a bastard child no one ever talks about.

AEInteractWithUser was mentioned in Apple’s Technical Note TN2106:Scripting Interface Guidelines where it said “Before attempting to interact with the user in response to a scripting command, call AEInteractWithUser. If it returns an error, do not interact – either do without the user interface, or fail. This lets scripts specify whether or not they want to allow interaction.”

The “AS hole” said "It seems … you do not need to call AEInteractWithUser () for the library or routine on the side displaying the UI, but first execute it once to completely initialize the AppKit framework.

Your book said “AEInteractWithUser() call is part of the Carbon framework, and if the result is not 0 the script will throw an error (No user interaction allowed).”

AEInteractWithUser was mentioned in unhelpful ways in developer.apple.com under sections on kAECanSwitchLayer, kAEWaitReply, AESendMode, kAEDefaultTimeout.

It was mentioned in unhelpful ways a lot in apple’s mailing list.

After searching a long time I found the first useful thing on developer.apple.com in a notice from Apple that mentioned the 3ed parameter (idleProc) of AEInteractWithUser was modified in OS X v10.11. This notice finally said what the parameters and return value is: AEInteractWithUser(_: Int32, _: NMRecPtr, _: AEIdleUPP!) -> OSErr. I’m not sure what the first parameter is but in most of the example I’ve seen it’s -1 and now I know it’s a Int32. I think it might be some kind of number used to decide when to time out. Often the parameter got set to kAEDefaultTimeout and kNoTimeOut which further supports the timeout idea.

I don’t know what NMRecPtr is either. Nothing came up in Xcode help or dash but looking at examples using it seems to get used a lot with Notifications. So perhaps NMRecPtr is a pointer to a notification manager record.

I know what the third parameter is but I’m not sure how it is used for AEInteractWithUser. If I understand idleProc correctly it is used to handle things while waiting for the event manager to get back to the app.

Then after a lot more searching I found a site called stpeterandpaul.ca that mentioned a lot about AEInteractWithUser but it is on a site I know nothing about. Worse yet the full URL is http://stpeterandpaul.ca/tiger/documentation/AppleScript/Conceptual/AppleEvents/responding_aepg/chapter_6_section_2.html and the tiger in the URL suggests it’s old information. But interesting enough the URL also suggests the web page is stored under conceptual things related to AppleScript and responding to AppleEvents.

This is one majorly under documented thing.

Shane can you tell me if what is written in the “Interacting With the User” section of the web page is correct and if any of my guesses are correct.

Bill

You’re overthinking things – you really don’t need to worry about any of that.

The problem it solves is this: if you run, say, a dialog using my Dialog Toolkit, and you omit the AEInteractWithUser(), it will still work fine in most places. But if you run it from Apple’s built-in Scripts menu, for example, the dialog will behave strangely.

I took this up with the Apple engineers, and their response was to use AEInteractWithUser() roughly as I used it elsewhere here. Some applications may require it be called before they will show a dialog properly, so the easiest thing is just to include whenever you’re going to show a panel or other dialog via ASObjC.

Shane,

No that wasn’t why I wanted to know. I was entering it into the ASObj-C database. Everything else I explained but I didn’t know anything about AEInteractWithUser beyond use this just in case. It looked stupid to have almost nothing. I thought it would be easy to look up but it turned out not to be.

So do you know if what was on the web page was correct? It is really weird to puts details in everything but this one thing.

I have used this before and never had any troubles.

Bill

FWIW, I think that’s a fine summary: “If you are going to show a UI element such as a window or panel via ASObjC code, you should include this to ensure it will work from any host.” You can’t change the other arguments even if you wanted to, and they’re things so arcane you’re just going to put people off if you go into detail.

Shane,

So do people usually use -1 for the first parameter and missing value for the other 2. I never was sure what an idleproc would even be used for. Assuming the NMRecPtr, second parameter, is a pointer to a notification manage record I assume you can’t enter anything for the parameter except missing value because ASObj-C can’t handle pointers.

But the first parameter looks like it might be useful. I’ve seen kAEDefaultTimeout and kNoTimeOut for this. It certainly looks like it allows the user to choose between a default timeout or never timeout. Although I can see how never timing out could get people in trouble. A few times I seen other small number in the first parameter. I assume this is just setting the number of somethings before it times out. Shouldn’t the first parameter be documented?

Bill

IMO, no. But I suppose it depends on whether you’re trying to help people learn how to use it in ASObjC, or whether you want to document everything for documentation’s sake.

I tend to think that the more you stray off into detail that’s of no practical use, the more you’re just going to make eyes glaze over.

Shane,

So you would recommend just saying to always put -1, missing value, missing value in the 3 parameters and that’s it. I guess I am used to fully documenting things but in the end I want to do what works best for the user. If that’s all they should ever use then that’s all I need to put in. Although it does feel weird to not fully document something. You have actually taught this stuff to others for years in groups and in documentation you wrote so you are the expert here. So I’ll just put what goes in the parameters and that’s it.

Bill

Shane,

Here is what I entered into the database for AEInteractWithUser. Is this ok?

You might have to click the image to see it. It’s kind of tiny in the current size.

Bill

You might want to make it clear that it applies to dialogs other than standard AppleScript dialogs.

And you should list it as belonging to the Carbon framework, not HIToolbox. Where there are subframeworks like that, the main framework should be loaded.

Shane,

I change the start of the description to “AEInteractWithUser should be called before opening an ASObj-C panel or dialog. This is not needed for regular AppleSript dialogs. Some dialogs and …”

The database no longer mentions HIToolbox and the class is now listed as Carbon. The item type is now listed as a carbon function.

Bill

Yep, that covers it.