AIAppContextSuite - It's purpose and correct use?

Question

Hi all,
As the title suggests, I'm interesting in knowing more about what this suite is for and in what situations it would be used if anyone could shed some light?
What interests me most is the following line in the SDK Documents:
Most plug-ins will not need to use these functions because Illustrator manages the context. In rare situations, however, a plug-in may need to make changes to the context. For example, if a plug-in can be called directly by the operating system, Illustrator will not have established the context. If the plug-in wants to make SDK calls in response, it should use PushAppContext() and PopAppContext().
So how would a plug-in be called directly by the operating system? What would be the correct steps to take to achieve this?
Thanks!
-W

Answer 1

It's a little hard to explain, but sometimes you can end up in a state where the API & your plug-in are out of step. This mostly happens when you respond to things that don't originate in Illustrator. For example, we use Qt for our GUI and if clicking a button on a Qt dialog caused me to have to ask something of the AI SDK, chances are I have to push the context first or it won't work. I imagine you'd see the same thing if you wrote a dialog using straight OS calls and responded to a click or something like that there too.
The results are fairly unpredictable. In some cases, the calls might work for a while and then suddenly stop with strange symptoms. I've seen AIDocumentSuite::GetDocument() return garbage or return odd error results, things like that. Push the context and it magically goes away.
To assist with this kind of thing, I wrote a class to do that automatically for me and eventually I noticed that Adobe did the samething in their sample code If you check out AppContext.h/cpp you'll see a fairly neat class. You just basically declare a variable of that type when you need to do something and that's it -- it does the rest. For example:
void foo()
AppContext context;
// do something with the API
That will push the context in its constructor, and pop it in its destructor. Pushing & popping the context never seems to hurt, though obviously its wasteful if its unnecessary. Hopefully that answers your question, but if not post again and I can try to clarify!