Re: [platform-ui-dev] Context API confusion (very long)

[Chris McLaren <Chris_McLaren@xxxxxxxxxx>]

Easy answers for you. All of this was
radically simplified this week. (I got debug from head and checked out
how you were using things so I knew I wouldn't break the build)

1. Your one and only entry point to
the contexts API:
IWorkbenchContextSupport contextSupport
= IWorkbench.getContextSupport() 

2. You can get the *real* context manager
for the workbench like this (you should not be creating your own, or it
won't play with keybindings, etc..):
IContextManager contextManager = contextSupport.getContextManager();

3. To request that a context be enabled:
EnabledSubmission enabledSubmission
= new EnabledSubmission(null, null, "myContextId");
IWorkbench.getContextSupport().addEnabledSubmission(Collections.singletonList(enabledSubmission));

4. To withdraw that request:
IWorkbench.getContextSupport().removeEnabledSubmission(Collections.singletonList(enabledSubmission));


Extra notes:

a. Make sure to keep around your reference
to enabledSubmission after you request that a context be enabled. You need
this reference to withdraw your request later.

b. Withdrawing your request doesn't
necessarily mean your context will be disabled - some other plugin may
have put in an EnabledSubmission for this context as well. The context
manager enables a context if one or more plugins request it to be enabled.
(notice that you do not have access to IMutableContextManager.setEnabledContextsIds,
even if you try to cast contextManager to it). The context manager protects
itself - you must submit a request in the manner described above.

c. The first two parameters of enabled
submission allow you to specify that the workbench should only enable your
context when a certain part and/or perspective is active, a convenience
to use if you choose (the workbench will take care of the rest), or you
can manage this yourself using the global listeners. Using null and null
as I have done in this example means you want it enabled independent of
what part or perspective is active).

d. Notice the term is now 'enabled'.
The term 'active' should no longer be used. I will double check the API
to make sure of this for clarity..


That should be pretty much everything
you need to know (a lot simpler, eh?). Let me know what I missed after
you digest these changes.
Chris.

Jared Burns <jaredburns@xxxxxxx>
Sent by: platform-ui-dev-admin@xxxxxxxxxxx

02/24/04 02:19 PM

Please respond to
platform-ui-dev

To	platform-ui-dev@xxxxxxxxxxx
cc
Subject	[platform-ui-dev] Context API confusion (very long)

Hola.

There seems to be a lot of API related to contexts floating around, but
I 
can't figure out which is the right one for me. Get comfortable. ;-)

############################################
#  Background info to make sure I have my story straight
############################################
A workbench page can return an IWorkbenchPageContextSupport, which can
then 
provide me an ICompoundContextActivationService. This service allows me
to 
register an IContextActivationServiceListener. The listener, in turn, is
notified of ContextActivationServiceEvents, which can tell me which 
IContextActivationService it came from and haveActiveContextIdsChanged().
However, it doesn't appear to tell me which contexts have been activated
or 
deactivated.

A workbench window can return an IWorkbenchWindowContextSupport, which
returns 
an IContextActivationService (not to be confused with an 
ICompoundContextActivationService) which allows me to register an 
IContextActivationServiceListener that can then do the same thing as 
described above.

A workbench can return an IWorkbenchContextSupport, which provides an 
ICompountContextActivationService (like the workbench page, but not the
workbench window), and an IContextManager. An IContextManager can tell
me 
about the set of "defined" context IDs and also about the set
of "enabled" 
context IDs. An IContextManager also lets me register an 
IContextManagerListener which is notified of ContextManagerEvents. These
events tell me which context manager they came from and whether the set
of 
defined or enabled contexts has changed. But it doesn't tell me *which*
contexts have been enabled/disabled or defined(/undefined?). An 
IContextManager also provides access to IContext objects. IContexts let
you 
register IContextListeners on them and an IContextListener provides a 
ContextEvent, which tells you which context has changed and what has happened
to it (which property has changed).

There's also this thing called a ContextManagerFactory, which provides
a 
static factory method for creating an IMutableContextManager. An 
IMutableContextManager extends IContextManager and lets you set which 
contexts are enabled.

############################################
# Hopes and dreams in Debugland (redux)
############################################
Back in our code I have a view. When the user selects things in the view,
I 
want to activate contexts (I know which contextIds to activate). I also
have 
a listener. This listener has a set of context IDs that it cares about.
When 
these contexts are activated, it wants to know about it so it can respond.

Additionally, I'd like to be able to bind certain actions to contexts so
that 
they only appear at the right time. I'd like the actions to respond to
the 
contextIds that are activated by the view (and others, but the ones the
view 
activates will be the most interesting).

############################################
# Now I'm in trouble...
############################################
For my view to activate contexts, I need an IMutableContextManager. However,
the only API I've found that provides an IMutableContextManager is the
ContextManagerFactory and the context manager that it returns seems to
be 
totally disconnected from the rest of the workbench.

Currently, that's what I do. The view creates its own IMutableContextManager
and activates/deactivates contexts in this manager. My listener then 
registers as an IContextListener on all of the context manager's IContexts.

The problem here, of course, is that I'm in a context manager that's separated
from reality. Activating contexts in my context manager won't cause the
action (command) filtering that we want. It also means that if someone
other 
than the view activates one of the interesting contextIds, my listener
won't 
hear about it.

############################################
# Gimme, gimme :-)
############################################
Based on all this, I have some requests for the API.

1. Provide IMutableContextManagers. For clients to be able to activate
contexts at the various levels, the API needs to expose 
IMutableContextManagers. I haven't found a way to get to one from the 
workbench, window, or page level. In fact, IMutableContextManagers seem
a lot 
more interesting than IContextActivationServices, which they currently
provide.
2. IContextActivationService seems to promise more than it delivers. In
the 
class comment, it says that these things are supposed to "allow clients
to 
manage context activation," but I don't see anything on the API that
lets you 
manage things. Only access what's currently active. As they stand now,
in 
fact, I don't know why a client would want one of these. Maybe the JavaDoc
could explain?
3. Beef up the description of the various I*ContextSupport level. Trying
to 
figure out which level to use is tough right now. It would be nice if the
JavaDoc would provide examples of when you'd want to use each level.
4. Provide fewer "supports". Having separate I*ContextSupport
interfaces for 
every level makes it really hard (for me, at least) to get your head around
the API. Providing support at every level might be necessary (but I can't
really tell without #1), but it would make things simpler for clients if
each 
level at least provided the same kind of object.
5. Make the I*ContextSupports consistent? I don't understand why the top
and 
bottom levels (IWorkbench and IWorkbenchPage) provide 
ICompountContextActivationServices but the middle layer (IWorkbenchWindow)
provides an IContextActivationService. If this arrangement is intentional,
could the reason be explained in the JavaDoc? If it's not, then making
all 
three levels consistent would make the APIs a little less confusing.
6. Add information to the IContext*Listeners' events. Clients (well, me
anyway) need to know *what* has changed, not just that something has changed.
Instead of methods like haveActiveContextIdsChanged(), maybe provide 
getActivatedContextIds() which returns all context IDs that have been 
activated? If nothing's changed, you return an empty list. This is just
like 
returning false to the current method. But if they *have* changed, you
can 
now tell clients which contexts have been activated so they don't have
to go 
grovelling.
7. Reduce the number of listeners. Being able to register as a listener
on a 
"context activation service," "context manager," *and*
a context seems like 
way too much. It's another of those things like #2 that makes it hard to
get 
your head around the API. Do I want to be an 
IContextServiceActivationListener, an IContextManagerListener, or an 
IContextListener? I really just want to have one listener interface that
is 
informed about context events. The events should be able to tell me all
the 
relevant info - which contexts were defined, which were enabled, and which
were disabled?
8. Define the difference between "active" and "enabled."
Maybe it's defined 
somewhere, but I haven't bumped into it. An IContextActivationService talks
about contexts in terms of "activation" and an IContextManager
talks in terms 
of "enablement" (and "defined", but I think that term
is pretty 
self-explanatory).  IContexts talk about *themselves* in terms of
enablement 
and make no mention of activation. Are the "active" references
in other 
places just holdovers from a period where that was the term for "enabled"?
Or 
is there a difference? If so, can this difference be explained in the 
JavaDoc? If not, can all references to "active" be updated to
"enabled" for 
consistency?

If you made it through all this, thanks for your patience. I'll understand
if 
it takes a few days to get some answers. :-) 

Thanks,
- Jared

_______________________________________________
platform-ui-dev mailing list
platform-ui-dev@xxxxxxxxxxx
http://dev.eclipse.org/mailman/listinfo/platform-ui-dev