This Bugzilla instance is a read-only archive of historic NetBeans bug reports. To report a bug in NetBeans please follow the project's instructions for reporting issues.
IZ entry for API review of Quick Search API.
Main material for review is javadoc of new proposed infrastructure module, org.netbeans.spi.quicksearch which I will attach in zipped form. javadoc includes all info you may need - proposed architecture, SPI and usage explained.
Created attachment 62482 [details] Quick Search SPI Javadoc
Other related materials are: UI spec - http://xdesign-tools/projects/netbeans/quicksearch_feature/index.html Wiki page - http://wiki.netbeans.org/QuickSearch
Notes for reviewers - I would like to integrate into 6.5 M1, which is tight deadline. So I would like to organize inception API review meeting early next week and ideally get result of "review passed with some change requests". So if you want to participate on review, please study javadoc a bit and wait on my meeting invitation. API itself is very easy and straightforward, as all my APIs :) so don't be scared. Unfortunately source code is in non public hg repo now, so maybe I can publish some build somewhere for you to try out current state of feature from user's point of view.
I don't seem to be able to access the UIspec. Is http://xdesign-tools/ publicly visible? There are also some links on your wiki page affected by this.
Ondro, we should move all relevant info to public wiki. Anyway UI spec is not direct subject of review. Anyway see flash demos (attached to wiki page) to understand what is this feature about.
Thanks for the notice. The UI spec as well as storyboards have been moved to public sites: UI spec: http://ui.netbeans.org/docs/ui/quicksearch/index.html storyboard: http://ui.netbeans.org/docs/ui/quicksearch/storyboards/index.html
Y01 Change stability to official - that is the stability this API shall have at the time of release of 6.5 and everyone shall be aware that before first public release we are not yet in compatible mode. Y02 Remove getLookup and CategoryDescription. Create a class named SearchProviderDescription with factory method: create(Class<? extends SearchProvider>, String prefix, String ...) and in the layer create a registration like: <folder name="QuickSearch"> <file name="org-netbeans-mymodule-mypackage-MySearchProviderImplDesc.instance"> <attr name="instanceCreate" methodvalue="...SearchProviderDescription.create"/> <attr name="searchProvider" stringvalue="org.netbeans.mymodule.mypackage.MySearchProvider"/> <attr name="category" stringvalue="..."/> <attr name="commandPrefix" stringvalue="..."/> </file> </folder> Y03 Writer a wizard to create all these files, to really help people write SearchProviders
VS01: The API does not seem to support multi-keybindings. A multi-keybinding is a sequence of KeyStrokes and some shortcut profiles (eg. Emacs) heavily use multi-keybindings. I think anywhere where KeyStroke is used now should actually be Collection<? extends KeyStroke>. Otherwise search providers won't be able to supply correct shortcuts for the actions they found.
JB01: I remember, that requirement was to highlight part of result which match given pattern. Is this use case supported? How?
Created attachment 62656 [details] new version of javadoc
SA01: since the search results are pure Runnables there is no way to provide their 'enabled' state. i think it would be handy especially for context sensitive actions displayed in 'recent search results' section.
I attached new version of javadoc, in which: Y01 is done. Y02 is done in slightly different way after off line discussion with Jarda. xml registration syntax changed to: <folder name="QuickSearch"> <folder name="MyCategoryID"> <!--Attribute for localization - provide localized display name of category!--> <attr name="SystemFileSystem.localizingBundle" stringvalue="org.netbeans.modules.yourmodule.YourBundle"/> <!--Attribute for command prefix - used to narrow search to this category only!--> <attr name="command" stringvalue="p"/> <!--Attribute for category ordering!--> <attr name="position" intvalue="200"/> <!--Note that multiple providers can contribute to one category!--> <file name="org-netbeans-module2-package2-MySearchProviderImpll.instance"/> <file name="org-netbeans-module2-package3-MySearchProviderImpl2.instance"/> </folder> </folder> re Y03: agreed, will do for 6.5 Milestone2 re VS01: good point, agreed, I didn't know about multi shortcuts. Why Collection and not List? Isn't there some order of individual shortcuts defined? re JB01: Nice shot, it's not solved yet. I wanted you to help me with this on today's meeting :) Probably we should enhance SearchResponse to allow providers to specify what should be emphasized.
VS01: Ehrr, yes, sorry, I meant to say List<? extends KeyStroke>.
MS01: What about conflicting names? Is there going to be some way to distinct them from each other (ie, action names)
msauer: Users must be able to distinguish between the actions (and know what they are invoking), therefore there should be no conflicting names. Instead, where there are multiple actions with the same name, we should allow only the one which makes sense in given context. Or did I misunderstand? Can you give a specific example please?
olangr: I've meant something like 'Checkout' -- there is such action for both CVS and SVN, entries look same 'Checkout...' => user doesn't know what he's invoking. So I had an idea to provide some second-level distinguish for such cases.
Thanks, I see. In this case, the names should probably be "CVS checkout" and "SVN checkout". Since the action search ignores the original context of the actions (in case of checkout, it is given by submenu the actions are present in), we should probably provide this context by using different action name than is used in the main menu. Similarly, we should *not* have "Members" and "File Members" actions for inspect actions in Navigate -> Inspect menu. Instead, there should be "Inspect Members" and "Inspect File Members" actions. OL01: Also, we've been previously discussing the possibility of (manual) meta-tagging of actions/options for items reportedly searched for by different keywords and searching through these meta-tags. I.e., searching for font-size would bring up the fonts&colors dialog, because it would be meta-tagged, despite that it does not contain the word font-size anywhere. It is the sound of far future, but does the API allow for that?
Jan, Max, Milan, Vita, Standa and Jarda, thank you for review! Nice to talk to you. Here comes poor man's opinion document (I know I shouldn't write it myself, but anyway) ---- API was reviewed and accepted with several following requests. Requests must be implemented to final 6.5 release but don't prevent QuickSearch API to be integrated into 6.5 Milestone 1 build. Requests: TCR01: Change KeyStroke to List<? extends KeyStroke>, both in SearchRequest and SearchResponse as requested in VS01, to support multi key binding. TCR03: Support html in displayName parameter of SearchResponse.add(....,String displayName, ...) to enable providers to bold found text or emphasize what they need in display name of result item. Enhance javadoc to remind clients that they can use basic HTML. That solves JB01. TCR03: Implement Y03 (Wizard) TCR04: Have String displayHint in basic SearchResponse.add(....) method as well, because it will be used to solve duplicate names in UI (see MS01). How and where to display this hint is up to olangr, however tooltip looks probable. TCR05: Runnable that is returned from providers should be aware that it may be called at a time when run body can't be performed, because of changed conditions like active context or so on (especially when action is invoked from Recent Searches list). Providers are expected to signal unsuccessful run by writing into status line and/or beep. I need to document this in SearchResponse.add(....) javadoc. If this "javadoc API" proves insufficient, we will go with TCA01. -------------------- Advices: TCA01: If TCR05 is not enough, then add method SearchResponse.addResult(Action action) so that it's possible to ask action.isEnabled() and so on. Variant of this is SearchResponse.addResult(StateRunnable action, .....) where StateRunnable has isEnabled() method. (this solves SA01) TCA02: Support smart and full type of search, similarly like in code completion - add new method SearchRequest.getSearchType(). This TCA depends on if and how search types will be needed in UI. ----
re OL01: Yes, API do support that. Providers are free to implement any algorithm in SearchProvider.evaluate(...) method, so Actions provider can search for meta tags anywhere. The biggest work here is to actually create meta tags for actions and agree on a place where they would be stored. Implementation part isn't hard here.
OK, API review is finished, reassigning back to me, but leaving open to not forget on TCRs and TCAs.
TCR01 implemented in http://hg.netbeans.org/main/rev/dfed0adb164c I decided to invalidate TCR04, as UI spec seems to not enforce existence of a hint for result item, so implementation should be aligned and have it only optional too, as it is now. Please speak up if you think my decision is wrong, thanks.
TCR02, TCR05 fixed in http://hg.netbeans.org/main/rev/5dd3843041d2 http://hg.netbeans.org/main/rev/52dbf7b07a76
Integrated into 'main-golden', available in NB_Trunk_Production #285 build Changeset: http://hg.netbeans.org/main/rev/5dd3843041d2 User: Dafe Simonek <dsimonek@netbeans.org> Log: #136671: html tagging in result's htmlDisplayName explained
All TCRs completed, closing this api review, thanks.