Changeset 10317 in josm for trunk/src/org/openstreetmap

Timestamp:

2016-06-02T23:01:09+02:00 (8 years ago)

Author:

Don-vip

Message:

fix #12904 - Documentation of DialogsPanel (patch by michael2402)

Location:

trunk/src/org/openstreetmap/josm/gui/dialogs

Files:

• DialogsPanel.java (modified) (5 diffs)
• ToggleDialog.java (modified) (4 diffs)

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

@@ -18 +18 @@
 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<>();
@@ -28 +31 @@
     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();
@@ -50 +65 @@
     }
 
+    /**
+     * 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);
@@ -72 +95 @@
         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);
 
@@ -94 +118 @@
      */
     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
     }
 

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

@@ -605 +605 @@
         }
 
+        /**
+         * This is the popup menu used for the title bar.
+         */
         public class DialogPopupMenu extends JPopupMenu {
 
@@ -627 +630 @@
         }
 
+        /**
+         * Registers the mouse listeners.
+         * <p>
+         * Should be called once after this title was added to the dialog.
+         */
         public final void registerMouseListener() {
             popupMenu = new DialogPopupMenu();
@@ -826 +834 @@
     }
 
+    /**
+     * 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;
@@ -866 +884 @@
     }
 
+    /**
+     * 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);