Bug 49647 - Support SPI: show a project properties dialog with a list of panes
Support SPI: show a project properties dialog with a list of panes
Status: RESOLVED FIXED
Product: projects
Classification: Unclassified
Component: Generic Projects UI
4.x
All All
: P2 (vote)
: 4.x
Assigned To: Petr Hrebejk
issues@projects
buildsys-e-cand
: API, API_REVIEW_FAST
Depends on: 51151
Blocks: 41837 49634
  Show dependency treegraph
 
Reported: 2004-09-28 18:00 UTC by Jesse Glick
Modified: 2005-01-16 19:22 UTC (History)
0 users

See Also:
Issue Type: ENHANCEMENT
:


Attachments
Proposed API and it's implementation (34.36 KB, patch)
2005-01-03 16:22 UTC, Petr Hrebejk
Details | Diff
Fixed javadoc (6.63 KB, text/plain)
2005-01-11 17:04 UTC, Petr Hrebejk
Details
Demo of the API usage (9.44 KB, patch)
2005-01-11 17:06 UTC, Petr Hrebejk
Details | Diff

Note You need to log in before you can comment on or make changes to this bug.
Description Jesse Glick 2004-09-28 18:00:48 UTC
Desirable for most project types.
Comment 1 Petr Hrebejk 2005-01-03 16:22:56 UTC
Created attachment 19440 [details]
Proposed API and it's implementation
Comment 2 Petr Hrebejk 2005-01-03 16:26:05 UTC
Attached diff shows the proposed API and It's implementation

API: 
ProjectCustomizer.java
  
Implementation:

CategoryModel.java
CategoryView.java
CustomizerDialog.java
CustomizerPane.form
CustomizerPane.java

The CategoryModel could be published later as an interface if necessary. 

Comment 3 Jesse Glick 2005-01-04 02:07:20 UTC
Missing SPL in ProjectCustomizer.java.


Javadoc tip: avoid BiCapitalizedWords (with or without <code>) when
they are not in fact meaningful, so you don't confuse readers who are
expecting such names to be important. Javadoc for ProjectCustomizer says

"Support for creating standard ProjectCustomizer dialog."

But ProjectCustomizer does not extend JDialog, it is just a place for
factory methods, so this Javadoc is more confusing than helpful - why
is the Javadoc for the class referring to its own name?? Use something
more descriptive like

"Support for creating dialogs which can be used as project
customizers. The dialog may display multiple panels or categories.
@see org.netbeans.spi.project.ui.CustomizerProvider"

Same in constructor Javadoc, etc. And when referring to
CustomizerProvider, use {@link ...} or @see or at least <code>.
Similarly, avoid abuse of capitalization in Javadoc like

"@param categories Array of Categories to be shown in the dialog."

The Javadoc will already make it clear that the type is Category[],
and "Categories" is bad because there is no such class. Also repeating
the same word as a parameter or type name loses the opportunity to
give a synonym which can help someone understand the word better.
Simply use e.g.

"@param categories list of panels to be shown in the dialog (may not
be empty)"

BTW do not capitalize the description in a @param. Similarly,

"@param componentProvider Implementation of CategoryProvider which
creates components..."

The beginning is just noise; the type is obvious in the generated
Javadoc, and clearly an implementation is wanted, since the type is an
interface. And in fact you mistyped the interface name anyway! Simplify to

"@param componentProvider creator of GUI components..."


createCustomizerDialog should mention if you need to pack() it -
probably not? I assume you need to setVisible(true). Should also
mention if it will be modal or not.


'public' modifier in an interface (CategoryComponentProvider) is
redundant.


Should Category.icon be an Image? Icon seems more normal. Doesn't
really matter I guess.


Shouldn't createCustomizerDialog take a HelpCtx? Even if it isn't
working yet? :-)


Why is it permitted by the impl for preselectedCategory to be null,
but the Javadoc does not mention this possibility? And why is it
permitted by the impl for preselectedCategory to not be a name of any
supplied category?


Would be nice to see a diff of changes in j2seproject to use the new
SPI, as well as comments from someone working on some other project
type confirming that the proposed SPI is satisfactory.
Comment 4 Jaroslav Tulach 2005-01-05 12:43:35 UTC
My minor suggestion is save one class by making Category toplevel and
add factory methods from ProjectCustomizer to it. At least there will
not be problem with javadoc for ProjectCustomizer ;-)
Comment 5 Petr Hrebejk 2005-01-05 13:49:32 UTC
Hmm, I'm not sure. The way how it looks like now seems a bit less
confusing to me as all the classes in
org.netbeans.spi.project.ui.support have descriptive names. User can
guess what they should be used for. ProjectCustomizer with the two
innerclasses contains all things needed for creating a customizer,
nicely separated. Having createDialog method in the Catogory may save
one class but it does not logicaly belong into it, IMO.
Comment 6 Jesse Glick 2005-01-06 23:41:12 UTC
I agree w/ Petr that it's a bit clearer for Category to be a nested
class, but I don't feel strongly about it.
Comment 7 Petr Hrebejk 2005-01-11 17:04:59 UTC
Created attachment 19622 [details]
Fixed javadoc
Comment 8 Petr Hrebejk 2005-01-11 17:06:24 UTC
Created attachment 19624 [details]
Demo of the API usage
Comment 9 Petr Hrebejk 2005-01-11 17:09:18 UTC
Tried to fix the javadoc flaws mentioned by Jesse. Alsso attached the
demo of the usage. I would like to merge that tomorrow. Still
experimenting w/ the HelpCtx parameter. It should not be necessary as
the help for current panel should be shown. Will see. If I find it
usefull I will add the parameter into the factory method.  
Comment 10 Jesse Glick 2005-01-11 20:08:00 UTC
Don't worry too much over Javadoc appearance, that can always be
improved later.
Comment 11 Petr Hrebejk 2005-01-16 19:22:15 UTC
Proposed changes checked in.


By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2012, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo