Bugzilla – Full Text Bug Listing
| Summary: | add parameterized commands to open/show java elements | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| Product: | [Eclipse Project] JDT | Reporter: | Christopher Daly <cjdaly> | ||||||||
| Component: | UI | Assignee: | JDT-UI-Inbox <jdt-ui-inbox> | ||||||||
| Status: | RESOLVED FIXED | QA Contact: | |||||||||
| Severity: | enhancement | ||||||||||
| Priority: | P3 | CC: | daniel_megert, dejan, douglas.pollock | ||||||||
| Version: | 3.2 | ||||||||||
| Target Milestone: | 3.2 M5 | ||||||||||
| Hardware: | All | ||||||||||
| OS: | All | ||||||||||
| Whiteboard: | |||||||||||
| Attachments: |
|
||||||||||
|
Description
Christopher Daly
Created attachment 32742 [details]
patch adds parameterized commands to open/show java elements
Created attachment 32802 [details] revised patch - specifies categoryId for commands Doug pointed out in related bug for a "show help topic" command (see Bug #123040) that these commands should give a categoryId. The only difference between this patch and the previous is I added: categoryId="org.eclipse.ui.category.navigate" to each of the 3 new commands in plugin.xml. Is it guaranteed that these commands do not show up on the keys page? They aren't right now, however I'm not really sure why this is so. Why don't you want them to show up on the keys preference page? They wouldn't be of any use, would they? (In reply to comment #5) > They wouldn't be of any use, would they? > These commands each have a required parameter, so binding to the raw (unparameterized) command will always fail at execution time. If you could bind a key to a parameterized command it might be interesting (though I'm not sure how useful) in this case. Doug, in my keys pref page I have a couple of commands like "Show View (View: Outline)". Are these parameterizations of org.eclipse.ui.views.showView? If so, how does this work and can a user define one? I think I answered my own question. from org.eclipse.ui.ide:
<key
sequence="M2+M3+Q O"
contextId="org.eclipse.ui.contexts.window"
commandId="org.eclipse.ui.views.showView"
schemeId="org.eclipse.ui.defaultAcceleratorConfiguration">
<parameter
id="org.eclipse.ui.views.showView.viewId"
value="org.eclipse.ui.views.ContentOutline" />
</key>
so you can specify parameter values for key bindings.
But I think commands with required parameters should only show up in the keys preference page if they have been parameterized as above.
While working on Bug 123040, I found some bugs in my own code. These will be fixed for the next integration build. However, I'll explain how things should be working. The two pieces influencing how it appears in the Keys preference page are the optional attribute on commandParameter, and the IParameterValues instance specified. If a parameter values class is specified, then it is used by the preference page to show the user the available options. If a parameter is optional, then it is possible to run the command with no parameters. Examples: showView has a parameter values and is optional. It will show all the available views as possible commands, as well as one which will simply prompt the user. displayHelp has no parameter values and is optional. It makes it possible for the user to bind to it with no parameter (which simply opens the help contents). Chris, you said binding a key to a parameterized command might be interesting (for the user). Can you elaborate? I can't see a use case. How would the user specify a parameter? (In reply to comment #9) > Chris, you said binding a key to a parameterized command might be interesting > (for the user). Can you elaborate? I can't see a use case. How would the user > specify a parameter? > I think doing it with showView is an example of both interesting and useful. See comment #7. This binds a key to show the outline view. If you use that view a lot but it gets buried in a tabbed group this would be useful. For these java commands a use case would be: maybe you keep needing to revisit a certain class, so you bind a key to open that particular class in the editor. I think this is interesting but I don't know if I'd really use it. Also I think plugin.xml is currently the only way do these bindings to parameterized commands. For a user to dynamically add a binding to a parameterized command like the java commands it would require some new UI that doesn't exist today (I think - Doug might correct me on that). Keep in mind, the purpose of this patch was not to bind the commands to keys but to be able to embed and invoke them from the context of user assistance documents. >the purpose of this patch was not to bind the commands to keys
>but to be able to embed and invoke them from the context of user assistance
>documents.
Why do you need the commands in JDT UI? Couldn't you use JDT UI APIs to do the same i.e. clicking the link executes some API code?
I have a question about this patch for any of the JDT people reading: The commands I defined use the IJavaElement handle identifier to identify the java element to open/show. This works fine for source elements, but for elements in Jar files it may not share well between users. For instance if I print the handle id for java.lang.Object it looks like this: =org.test/C:\/Program Files\/Java\/jre1.5.0_04\/lib\/rt.jar<java.lang(Object.class[Object So my question is, would it make more sense to support a different format instead or multiple formats? Another format I can imagine using would be the JavaDoc one. Are there methods I could use to obtain and resolve a Javadoc reference for a subset of java elements. I know this wouldn't work for stuff like CompilationUnit and PackageFragmentRoot, but it should work for type, method, field. JavaDoc would normally be resolved based on its location in source. I would need to resolve with the entire workspace as the resolution context. Are there other java element identification formats (besides handle identifier and javadoc) that should be considered? (In reply to comment #11) > >the purpose of this patch was not to bind the commands to keys > >but to be able to embed and invoke them from the context of user assistance > >documents. > Why do you need the commands in JDT UI? Couldn't you use JDT UI APIs to do the > same i.e. clicking the link executes some API code? > This would require that plugins for help or cheatsheets would have to add a dependency on JDT UI which would not work (circular dependencies). The dependency model we're going for is, - Clients like help and cheatsheets depend on org.eclipse.core.commands. - Specific commands and handlers are defined by the plugins that manage the artifacts and ui the commands need to deal with (e.g. java commands/handlers live in some JDT plugin) - If someone tries to execute a command and the plugin that defines it is not installed things should fail gracefully because the commands framework provides for this. I also think that handles aren't the best representation. Their format is internal, and they contain location specific conformation, e.g. project name/ source folder name, as you just mentioned. The Javadoc link format looks like a good idea to me. But you always need to know the project name as you search in the context of a project. Can you give an example of a cheetsheet you want to implement? Would it first create a project, then open type in the hierarchy ect? Can you really do that so that the cheetsheet provider dosn't have to implement any kind of specific action (e.g. that creates a project with a given classpath), but just uses commands to script? Or will you soon ask for a command that creates a Java project of a given name? (In reply to comment #14) > I also think that handles aren't the best representation. Their format is > internal, and they contain location specific conformation, e.g. project name/ > source folder name, as you just mentioned. > > The Javadoc link format looks like a good idea to me. But you always need to > know the project name as you search in the context of a project. Given an IJavaElement, how would I generate a fully-qualified JavaDoc reference for it (is there a method for this or would I have to write it)? Also, given a JavaDoc reference and project context, what would I call to resolve it to the IJavaElement? > > Can you give an example of a cheetsheet you want to implement? Would it first > create a project, then open type in the hierarchy ect? > Can you really do that so that the cheetsheet provider dosn't have to implement > any kind of specific action (e.g. that creates a project with a given > classpath), but just uses commands to script? > Or will you soon ask for a command that creates a Java project of a given name? > I didn't plan to ask for a command to create Java a project. I can imagine wanting a command to launch the various new wizards, but that wasn't on my current list either. Actually what I had in mind was the author of cheatsheet (or help, or intro) would create the Java project that goes with the cheatsheet and it would be installed via the update manager or (less likely) via CVS checkout. This means there should be commands to install a feature from an update site and to checkout a project from a CVS site. FYI, I just created bug #123921 to serve as the place to discuss what commands UA wants to have available for UA document authors in the 3.2 timeframe. > Actually what I had in mind was the author of cheatsheet (or help, or intro)
> would create the Java project that goes with the cheatsheet and it would be
> installed via the update manager or (less likely) via CVS checkout. This means
> there should be commands to install a feature from an update site and to
> checkout a project from a CVS site.
Re-reading this, I'm not sure if I was very clear. To clarify:
Step 1 of cheatsheet may say "first you need to install the sample code..." with a command link to install the sample project.
Step 2 says "To understand how to do <mumble>, look at how it's done in the implementation of method x() in class C." and there is a command link to C.x() which is code in the sample.
(In reply to comment #13) About the layering: You can always always create a cheatsheet.jdt plugin that knows jdt and offers the extra command that then can be used by cheatsheet implementors that want do JDT operations. I'm currently hesitating to release the patch you sent. I would like to know: - Is 'scripting' using commands the way Eclipse wants to go. I think it's a nice idea, but committing to it would mean a lot of new commands for all kind of functionalty we offer. There's already a lot of public API, ready to use. This new way will duplicate most of it. - Does this really work, or could it turn out that the argument infrastructure is too weak? E.g. if you tell the user to create a project, but the user changes the project name. Will your command scripts still work? (In reply to comment #15) > Given an IJavaElement, how would I generate a fully-qualified JavaDoc reference > for it (is there a method for this or would I have to write it)? No, we so far don;t use this notation, and we don't have code for that. > Also, given a JavaDoc reference and project context, what would I call to > resolve it to the IJavaElement? To find a IType, you use IJavaProject.findType, to find a member use IType.getField and IType.getMethod (and you have to test if that element really exists). > About the layering: You can always always create a cheatsheet.jdt plugin that > - Is 'scripting' using commands the way Eclipse wants to go. I think it's a > nice idea, but committing to it would mean a lot of new commands for all kind > of functionalty we offer. There's already a lot of public API, ready to use. > This new way will duplicate most of it. Martin, we would like to keep the commands close to where the APIs are. Your idea would definitely work, but would add more maintenance for what is essentially just another way of exposing APIs. We worked with Doug Pollock to add necessary enhancements to the command framework so that we can have this as a standard mechanism of accessing Eclipse without programming. We are adding support for this in cheat sheets, welcome and help and will be providing more use cases. You are right that APIs for this do exist, but one must write Java code in order to use them and make formal dependency on Java plug-in. Using the command reduces everything to presence or absence of the command. > - Does this really work, or could it turn out that the argument infrastructure > is too weak? E.g. if you tell the user to create a project, but the user > changes the project name. Changing values used intially for the command is not command's responsibility. It is up to the client (e.g. cheat sheet code) to check if the user changed the name manually. The role of the command is to be executed with a given parameter - that's all. So you say that there is some cheat sheet code? Some scripting inside a cheet sheet that calls commands, gets return values from commands that it can then use to call another command using that value as input? My feeling is that if you have such a scripting language built in (probably Javascript), it is also easy to build a bridge to use the regular API we have. But if you're convinced that these 3 commands are useful, I'm going to release them. As mentioned, it is important to us that these commands do not show up in the keys UI unless assigning them with a key makes sense. Cheatsheets have a notion of a state manager that actions can use to pass state between each other. We haven't hooked commands yet here and need to figure out how to use it to pass state, but my remark is simply that commands themselves should not be avare of it. What we are doing is adding support to invoke commands by serializing both the command and the parameters as one string. If/when we add some variable support, it will be resolved before it hits the command so commands will not 'feel' a difference. Chris, I agree with Martin that not all the commands should be accessible via key bindings. (In reply to comment #19) > But if you're convinced that these 3 commands are useful, I'm going to release > them. Thanks, but before release, remember the current patch uses handle ids for parameters. Based on the discussion above, I think the patch would be more useful if I used something like Javadoc or maybe Java search strings to identify the elements. If you agree, say so and I'll redo the patch along those lines. > So you say that there is some cheat sheet code? Some scripting inside a cheet > sheet that calls commands, gets return values from commands that it can then > use to call another command using that value as input? It's possible to have commands return values and have the caller use those return values, but right now that functionality isn't used. Cheatsheets use the commands to have some visual effect, like open a view or editor, to direct the user to some artifact in the workspace that the cheatsheet is discussing. > As mentioned, it is important to us that these commands do not show up in > the keys UI unless assigning them with a key makes sense. I think Doug handled this case. If I see any additional bugs there I'll file them. Chris, it would be useful if cheat sheets support the following: 1) for commands that return an object as a return value, store the object in the cheat sheet manager under a known key (say, 'buffer') 2) add support to accept the value of the buffer as the command parameter (say '$buffer'). This would allow us to pass the return value to the next command and does not require too much work. We may also tap into parameter serialization to reuse it for return value serialization. Ok, so I'm waiting for an updated patch! Created attachment 33451 [details] new patch - doesn't use handle identifiers Ok, here is the new patch. This allows references to Java types, methods and fields. Handling every kind of IJavaElement would be a lot like re-inventing handle identifiers but I don't think that is necessary for UA's needs. This handles binary types as well as source types. Searches are done in the context of a project, so the binary type would need to be referenced by the indicated project. This lead me into some JDT core strangenesses described in Bug #124801. There's javadoc in the JavaElementReferenceConverter class that describes what the element references look like. reviewed and released patch > 20060123 Thanks Chris for the nice patch. It is our understanding that these commands are currently only preliminary APIs. Can you test the usability of these commands in some real-world cheetsheet before M6? We would prefer to remove these commands again if it turns out that using commands in cheetsheets doesn't work out the way you planed it. The reason is, as mentioned, that opening a second kind of API means a lot of maintenance and requests for completness. We are experienced with Java API, having techniques to spec, maintain and evolve it; all this isn't the case for commands yet. (In reply to comment #25) > Can you test the usability of these commands in some real-world cheetsheet > before M6? We would prefer to remove these commands again if it turns out that > using commands in cheetsheets doesn't work out the way you planed it. Thanks Martin! I will report back here on useability before M6. |