Ticket #12904: patch-dialogs-panel-document.patch

src/org/openstreetmap/josm/gui/dialogs/DialogsPanel.java

@@ -17 +17 @@
 import org.openstreetmap.josm.tools.CheckParameterUtil;
 import org.openstreetmap.josm.tools.Destroyable;
 
+/**
+ * This is the panel displayed on the right side of JOSM. It displays a list of panels.
+ */
 public class DialogsPanel extends JPanel implements Destroyable {
     private final List<ToggleDialog> allDialogs = new ArrayList<>();
     private final MultiSplitPane mSpltPane = new MultiSplitPane();
@@ -27 +30 @@
      */
     private final List<JPanel> panels = new ArrayList<>();
 
+    /**
+     * If {@link #initialize(List)} was called. read only from outside
+     */
+    public boolean initialized;
+
     private final JSplitPane parent;
 
+    /**
+     * Creates a new {@link DialogsPanel}.
+     * @param parent The parent split pane that allows this panel to change it's size.
+     */
     public DialogsPanel(JSplitPane parent) {
         this.parent = parent;
     }
 
-    public boolean initialized; // read only from outside
-
+    /**
+     * Initializes this panel
+     * @param pAllDialogs The list of dialogs this panel should contain on start.
+     */
     public void initialize(List<ToggleDialog> pAllDialogs) {
-        if (initialized)
-            throw new IllegalStateException();
+        if (initialized) {
+            throw new IllegalStateException("Panel can only be initialized once.");
+        }
         initialized = true;
         allDialogs.clear();
 
@@ -49 +64 @@
         reconstruct(Action.ELEMENT_SHRINKS, null);
     }
 
+    /**
+     * Add a new {@link ToggleDialog} to the list of known dialogs and trigger reconstruct.
+     * @param dlg The dialog to add
+     */
     public void add(ToggleDialog dlg) {
         add(dlg, true);
     }
 
+    /**
+     * Add a new {@link ToggleDialog} to the list of known dialogs.
+     * @param dlg The dialog to add
+     * @param doReconstruct <code>true</code> if reconstruction should be triggered.
+     */
     public void add(ToggleDialog dlg, boolean doReconstruct) {
         allDialogs.add(dlg);
-        int i = allDialogs.size() - 1;
         dlg.setDialogsPanel(this);
         dlg.setVisible(false);
         final JPanel p = new JPanel() {
@@ -71 +94 @@
         p.setLayout(new BoxLayout(p, BoxLayout.Y_AXIS));
         p.setVisible(false);
 
-        mSpltPane.add(p, 'L'+Integer.toString(i));
+        int dialogIndex = allDialogs.size() - 1;
+        mSpltPane.add(p, 'L'+Integer.toString(dialogIndex));
         panels.add(p);
 
         if (dlg.isDialogShowing()) {
@@ -93 +117 @@
      * What action was performed to trigger the reconstruction
      */
     public enum Action {
+        /**
+         * The panel was invisible previously
+         */
         INVISIBLE_TO_DEFAULT,
+        /**
+         * The panel was collapsed by the user.
+         */
         COLLAPSED_TO_DEFAULT,
         /*  INVISIBLE_TO_COLLAPSED,    does not happen */
-        ELEMENT_SHRINKS         /* else. (Remaining elements have more space.) */
+        /**
+         * else. (Remaining elements have more space.)
+         */
+        ELEMENT_SHRINKS
     }
 
     /**

src/org/openstreetmap/josm/gui/dialogs/ToggleDialog.java

@@ -604 +604 @@
             return lblTitle.getText();
         }
 
+        /**
+         * This is the popup menu used for the title bar.
+         */
         public class DialogPopupMenu extends JPopupMenu {
 
             /**
@@ -626 +629 @@
             }
         }
 
+        /**
+         * Registers the mouse listeners.
+         * <p>
+         * Should be called once after this title was added to the dialog.
+         */
         public final void registerMouseListener() {
             popupMenu = new DialogPopupMenu();
             addMouseListener(new MouseEventHandler());
@@ -825 +833 @@
         return isShowing && isDocked && isCollapsed;
     }
 
+    /**
+     * Sets the button from the button list that is used to display this dialog.
+     * <p>
+     * Note: This is ignored by the {@link ToggleDialog} for now.
+     * @param button The button for this dialog.
+     */
     public void setButton(JToggleButton button) {
         this.button = button;
     }
 
+    /**
+     * Gets the button from the button list that is used to display this dialog.
+     * @return button The button for this dialog.
+     */
     public JToggleButton getButton() {
         return button;
     }
@@ -865 +883 @@
         // Do nothing
     }
 
+    /**
+     * Create a component with the given layout for this component.
+     * @param data The content to be displayed
+     * @param scroll <code>true</code> if it should be wrapped in a {@link JScrollPane}
+     * @param buttons The buttons to add.
+     * @return The component.
+     */
     protected Component createLayout(Component data, boolean scroll, Collection<SideButton> buttons) {
         return createLayout(data, scroll, buttons, (Collection<SideButton>[]) null);
     }