NetBeans Architecture Answers for PropertySheet API module

General Information

Question (arch-what): What is this project good for?
Answer: The property sheet is a generic user interface component and infrastructure for displaying and editing properties of objects.
Question (arch-overall): Describe the overall architecture.
WARNING: Question with id="arch-overall" has not been answered!
Question (arch-usecases): Describe the main use cases of the new API. Who will use it under what circumstances? What kind of code would typically need to be written to use the module?
WARNING: Question with id="arch-usecases" has not been answered!
Question (arch-time): What are the time estimates of the work?
WARNING: Question with id="arch-time" has not been answered!
Question (arch-quality): How will the quality of your code be tested and how are future regressions going to be prevented?
WARNING: Question with id="arch-quality" has not been answered!

Project and platform dependencies

Question (dep-nb): What other NetBeans projects and modules does this one depend on?
Answer: It uses various kinds of API's:
• NodesAPI - Property sheets primarily render the properties of objects encapsulated by nodes.
• ActionsAPI
• WindowSystemAPI
• OptionsAPI
• UtilitiesAPI
Question (dep-non-nb): What other projects outside NetBeans does this one depend on?
Answer: None.
Question (dep-platform): On which platforms does your module run? Does it run in the same way on each?
Answer: 100% pure Java. It should run anywhere.
Question (dep-jre): Which version of JRE do you need (1.2, 1.3, 1.4, etc.)?
Answer: It uses JRE 1.4.
Question (dep-jrejdk): Do you require the JDK or is the JRE enough?
Answer: JRE is enough.

Deployment

Question (deploy-jar): Do you deploy just module JAR file(s) or other files as well?
Answer: Classes belonging to this module do not reside in a standalone library. They are bundled together with other parts of the openide in openide.jar.
Question (deploy-nbm): Can you deploy an NBM via the Update Center?
Answer: Openide.jar can be deployed via AU center.
Question (deploy-shared): Do you need to be installed in the shared location only, or in the user directory only, or can your module be installed anywhere?
Answer: openide.jar needs to be in the system directory.
Question (deploy-packages): Are packages of your module made inaccessible by not declaring them public?
Answer: No.
Question (deploy-dependencies): What do other modules need to do to declare a dependency on this one?
WARNING: Question with id="deploy-dependencies" has not been answered!

Compatibility with environment

Question (compat-i18n): Is your module correctly internationalized?
Answer: Yes.
Question (compat-standards): Does the module implement or define any standards? Is the implementation exact or does it deviate somehow?
Answer: PropertySheetAPI defines an extension to java.beans.PropertyEditor, ExPropertyEditor which allows property editors implementing this interface to access information about the context in which a property is being rendered.
Question (compat-version): Can your module coexist with earlier and future versions of itself? Can you correctly read all old settings? Will future versions be able to read your current settings? Can you read or politely ignore settings stored by a future version?
Answer: Yes it is compatible with older versions. Legacy settings are supported for backward compatibility, but ignored.

Access to resources

Question (resources-file): Does your module use java.io.File directly?
Answer: No.
Question (resources-layer): Does your module provide own layer? Does it create any files or folders in it? What it is trying to communicate by that and with which components?
Answer: No.
Question (resources-read): Does your module read any resources from layers? For what purpose?
Answer: No.
Question (resources-mask): Does your module mask/hide/override any resources provided by other modules in their layers?
Answer: No.

Lookup of components

Question (lookup-lookup): Does your module use org.openide.util.Lookup or any similar technology to find any components to communicate with? Which ones?
Answer: Lookup is used along with reflection to invoke help, which may or may not be available depending on the presence of a help integration.
Question (lookup-register): Do you register anything into lookup for other code to find?
Answer: No.
Question (lookup-remove): Do you remove entries of other modules from lookup?
Answer: No.

Execution Environment

Question (exec-property): Is execution of your code influenced by any environment or Java system (System.getProperty) property?
Answer:

The following system properties are currently used by the property sheet implementation to affect its behavior in various ways. These are subject to change and should not be relied upon, but may prove useful in some situations:

• netbeans.ps.noCustomButtons - Boolean system property for the property sheet which, when true, hide the custom editor button that appears in the property sheet unless the cell is in edit mode.
• netbeans.ps.forceRadioButtons - Boolean system property for the property sheet which, when true, instructs the property sheet to use a radio button editor instead of the default checkbox editor for boolean values
• netbeans.ps.checkboxCaption - Boolean system property for the property sheet which, if true, means that a caption will be provided alongside checkboxes in the boolean editor
• netbeans.ps.hideSingleExpansion - Boolean system property for the property sheet which, when true, instructs the property sheet to hide the expansion handle for nodes that have only one property set (do not show a category called " properties" if it is the only category)
• netbeans.ps.neverMargin - Boolean system property for the property sheet which, when true, instructs the property sheet never to show a left-hand margin alongside the list of properties. This increases the available space to display property names and values at some aesthetic expense; it is useful on laptops with small screens.
• netbeans.ps.combohack - Boolean system property for the property sheet which, when true, forces the property sheet's combo box editor to use a heavyweight popup window, used to solve the above window manager problem in which the created heavyweight popup dimensions differ from those of the lightweight popup enough that the heavyweight popup could fit in the bounds of the parent, resulting in endless flipping between lightweight and heavyweight popups. This problem occurs on some pre-release versions of KDE for Linux.
• netbeans.ps.forcetabs - Boolean system property for the property sheet which, when true, forces each property set to be displayed in a separate tab (normally this is done only by providing a hint from a PropertySet via getValue("tabName").
• netbeans.ps.nevertabs - Boolean system property for the property sheet which, when true, disables use of tabs in the property sheet even if the property set provides a tab name via the above-mentioned hint
• netbeans.reusable.strictthreads - Boolean system property for the property sheet which, if true, causes an ISE to be thrown if any attempt is made to access or paint the property sheet from a thread other than the AWT event thread
• netbeans.ps.showHiddenProperties - Boolean system property for the property sheet which, when true, will cause it to display Node.Property objects even if they return true from isHidden(). The original behavior of the property sheet was to show these properties.

The code that handles these settings is in the class org.openide.explorer.propertysheet.PropUtils.

Question (exec-component): Is execution of your code influenced by any (string) property of any of your components?
Answer: PropertyEditorsProperties - A variety of hints that can be supplied to property editors to influence their behavior. The usual usage is to create a feature descriptor and set parameters on it:

Node.Property prop = new Node.Property (Boolean.TYPE, ...);
prop.setValue ("stringValue", new String[] { "yes", "no" });

The property sheet's display can be customized to a degree by a look and feel providing netbeans-specific keyed values. Principally this is useful in that the XML theme file for metal look and feel can be used to add these values to any look and feel that subclasses javax.swing.plaf.metal.MetalLookAndFeel; authors of look and feels which wish to provide customizations when their look and feel is used to provide UI display and behaviors for NetBeans may also provide custom values for these:

• Tree.altbackground - (java.awt.Color) UIManager key for a value which, if non null in UIDefaults, provides an alternate background color that should be used for every other row in the property sheet
• PropSheet.setBackground(java.awt.Color) Background color for expandable property sets
• PropSheet.selectionBackground - (java.awt.Color) UIManager key for a value which, if non null in UIDefaults, sets the background color for selected properties in the property sheet, overriding the default table selection color if present. Used to fulfil HIE color requirements on various platforms.
• PropSheet.selectionForeground - (java.awt.Color) UIManager key for a value which, if non null in UIDefaults, sets foreground color for selected properties in the property sheet, overriding the default table selection color if present. Used to fulfil HIE color requirements on various platforms.
• PropSheet.selectedSetBackground - (java.awt.Color) UIManager key for a value which, if non null in UIDefaults, sets the background color for expandable property sets when selected in the UI
• PropSheet.selectedSetForeground - (java.awt.Color) UIManager key for a value which, if non null in UIDefaults, sets the foreground color for expandable property sets when selected in the UI
• PropSheet.gridColor - (java.awt.Color) UIManager key for a value which, if non null in UIDefaults, sets the color for the grid of the property sheet table
• PropSheet.disabledForeground - (java.awt.Color) UIManager key for a value which, if non null in UIDefaults, sets the foreground color for disabled properties. May or may not be used, depending on the look and feel's implementation.
• netbeans.ps.iconmargin - (java.lang.Integer) UIManager key for a value which, if non null in UIDefaults, sets the integer spacing that should be used to left of the expansion handle for property sets.
• netbeans.ps.rowheight - (java.lang.Integer) UIManager key for a value which, if non null in UIDefaults, sets the sets a fixed row height for all elements in the property sheet. If not set, the value will be determined based on the font and/or the expansion handle icon, whichever is taller, the first time the property sheet is painted

Additionally, client properties may be used to affect behavior of PropertyPanel, a component for displaying individual properties. They are as follows:

• flat - (java.lang.Boolean) Client property of PropertyPanel applied using putClientProperty, to instruct a PropertyPanel instance to use a borderless UI suitable for use as a table renderer/editor. Also affects the behavior of combo boxes, enabling them to open on first click or focus, as appropriate for combo boxes displayed in a table. This property is obsoleted by PropertyPanel.PREF_TABLEUI which performs the same function when set as part of the PropertyPanel preferences bitmask, but is supported for backward compatibility
• suppressCustomEditor - (java.lang.Boolean) Client property of PropertyPanel applied using putClientProperty, to instruct a PropertyPanel instance to suppresses the presence of the custom editor button even if the property editor supports a custom editor.
• radioButtonMax - (java.lang.Integer n) Client property of PropertyPanel applied using putClientProperty, to instruct a PropertyPanel instance to use radio buttons instead of a combo box for properties whose property editor supports tags but supplies less than n tags.
• useLabels - (java.lang.Boolean) Client property of PropertyPanel applied using putClientProperty, to instruct a PropertyPanel instance to use the property's display name as the caption for checkboxes, and as the title of a TitledBorder in the case of radiobuttons (this latter usage only applies if radioButtonMax is also used). The use of labels is important for checkboxes, as it is the natural way to display the meaning of a checkbox in a panel, and the label of a checkbox is what checkboxes use to indicate they have keyboard focus.
Further, there are a few properties what affect the behaviors of inline editors in the property sheet:
• postSetAction - (javax.swing.Action) Object which, if provided from Property.getValue("postSetAction") will be run if and when the user changes the property value via the property sheet.
• initialEditValue - (java.lang.String) String which, if provided from Property.getValue("initialEditValue") will be used as the initial value when the user initiates editing the property. This is used to, for example, suggest values for code completion, without showing the suggested value when the property sheet is simply paintedapi>

XXX document the following keys passed sometimes to Feature.getValue(String) from org.openide.explorer.propertysheet code: stringValues, valueIcon, nodeDescription, propertiesHelpID, nameIcon

Question (exec-ant-tasks): Do you define or register any ant tasks that other can use?
WARNING: Question with id="exec-ant-tasks" has not been answered!
Question (exec-classloader): Does your code create its own class loader(s)?
Answer: No.
Question (exec-reflection): Does your code use Java Reflection to execute other code?
Answer: Reflection is used to invoke JavaHelp if present, when the user invokes help. Reflection is used to try to attach action listeners to the component supplied by legacy (deprecated) EnhancedPropertyEditor implementations to supply their own inline editor component. Reflection is used by the deprecated DefaultPropertyModel to attempt to locate getter and setter methods on a random bean. Reflection is used during decision-making whether "Restore Default Value" Action should be disabled or enabled. This is due to the backward compatibility with properties in old modules (or new incorrectly implemented properties). See #51907 for detailed description why we do so.
Question (exec-privateaccess): Are you aware of any other parts of the system calling some of your methods by reflection?
Answer: No.
Question (exec-process): Do you execute an external process from your module? How do you ensure that the result is the same on different platforms? Do you parse output? Do you depend on result code?
WARNING: Question with id="exec-process" has not been answered!
Question (exec-introspection): Does your module use any kind of runtime type information (instanceof, work with java.lang.Class, etc.)?
WARNING: Question with id="exec-introspection" has not been answered!
Question (exec-threading): What threading models, if any, does your module adhere to?
WARNING: Question with id="exec-threading" has not been answered!
Question (security-policy): Does your functionality require modifications to the standard policy file?
WARNING: Question with id="security-policy" has not been answered!
Question (security-grant): Does your code grant additional rights to some other code?
WARNING: Question with id="security-grant" has not been answered!

Format of files and protocols

Question (format-types): Which protocols and file formats (if any) does your module read or write on disk, or transmit or receive over the network? Do you generate an ant build script? Can it be edited and modified?
Answer: None.
Question (format-dnd): Which protocols (if any) does your code understand during Drag & Drop?
Answer: See format-clibpoard.
Question (format-clipboard): Which data flavors (if any) does your code read from or insert to the clipboard (by access to clipboard on means calling methods on java.awt.datatransfer.Transferable?
Answer: Cut/copy/paste functionality is supplied via standard Swing components. No special implementation is done.

Performance and Scalability

Question (perf-startup): Does your module run any code on startup?
Answer: No.
Question (perf-exit): Does your module run any code on exit?
Answer: No.
Question (perf-scale): Which external criteria influence the performance of your program (size of file in editor, number of files in menu, in source directory, etc.) and how well your code scales?
Answer: The property sheet is designed to perform minimal memory consumption as it paints, by reusing renderers, etc., and by and large it is quite efficient.
There may be some overhead to selecting a large number of objects with some common properties, since the property sheet will display the intersection of properties common to all selected nodes. In practice it is unusual for more than a few objects to be simultaneously selected.
Question (perf-limit): Are there any hard-coded or practical limits in the number or size of elements your code can handle?
Answer: None defined by PropertySheet code.
Question (perf-mem): How much memory does your component consume? Estimate with a relation to the number of windows, etc.
Answer: Minimal - that of a JTable, a few renderer components and a couple of lists. Renderers, editors and menus are shared between all property sheet instances in the JVM.
Question (perf-wakeup): Does any piece of your code wake up periodically and do something even when the system is otherwise idle (no user interaction)?
Answer: No.
Question (perf-progress): Does your module execute any long-running tasks?
Answer: No.
Question (perf-huge_dialogs): Does your module contain any dialogs or wizards with a large number of GUI controls such as combo boxes, lists, trees, or text areas?
Answer: No.
Question (perf-menus): Does your module use dynamically updated context menus, or context-sensitive actions with complicated and slow enablement logic?
Answer: No.
Question (perf-spi): How the performance of the plugged in code will be enforced?
WARNING: Question with id="perf-spi" has not been answered!