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

[Jared Burns <jaredburns@xxxxxxx>]

Sounds great. :-) I'll take a look.

Thanks,
- Jared

On Tuesday 24 February 2004 12:06 pm, Chris McLaren wrote:
> 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.singletonLi
>st(enabledSubmission));
>
> 4. To withdraw that request:
> IWorkbench.getContextSupport().removeEnabledSubmission(Collections.singleto
>nList(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