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

Timestamp:

2017-06-11T13:57:28+02:00 (7 years ago)

Author:

michael2402

Message:

See #14794: Documentation for the gui package

Location:

trunk/src/org/openstreetmap/josm/gui

Files:

• HelpAwareOptionPane.java (modified) (2 diffs)
• MapFrame.java (modified) (6 diffs)
• MapSlider.java (modified) (1 diff)
• MapStatus.java (modified) (6 diffs)
• MapView.java (modified) (1 diff)
• NameFormatterHook.java (modified) (1 diff)
• ScrollViewport.java (modified) (2 diffs)
• ShowHideButtonListener.java (modified) (1 diff)

trunk/src/org/openstreetmap/josm/gui/HelpAwareOptionPane.java

@@ -33 +33 @@
 import org.openstreetmap.josm.tools.WindowGeometry;
 
+/**
+ * Utility methods that display an option dialog with an additional help button that links to the JOSM help
+ */
 public final class HelpAwareOptionPane {
 
@@ -39 +42 @@
     }
 
+    /**
+     * A specification of a button that should be added to the options dialog
+     */
     public static class ButtonSpec {
+        /**
+         * the button text
+         */
         public final String text;
+        /**
+         * the icon to display. Can be <code>null</code>
+         */
         public final Icon icon;
+        /**
+         * The tooltip to display when hovering the button
+         */
         public final String tooltipText;
+        /**
+         * The help topic to link
+         */
         public final String helpTopic;
         private boolean enabled;

trunk/src/org/openstreetmap/josm/gui/MapFrame.java

@@ -131 +131 @@
     private final List<ToggleDialog> allDialogs = new ArrayList<>();
     private final List<IconToggleButton> allDialogButtons = new ArrayList<>();
+    /**
+     * All map mode buttons. Should only be read form the outside
+     */
     public final List<IconToggleButton> allMapModeButtons = new ArrayList<>();
 
@@ -294 +297 @@
     }
 
+    /**
+     * Enables the select tool
+     * @param onlyIfModeless Only enable if modeless mode is active
+     * @return <code>true</code> if it is selected
+     */
     public boolean selectSelectTool(boolean onlyIfModeless) {
         if (onlyIfModeless && !MODELESS.get())
@@ -301 +309 @@
     }
 
+    /**
+     * Enables the draw tool
+     * @param onlyIfModeless Only enable if modeless mode is active
+     * @return <code>true</code> if it is selected
+     */
     public boolean selectDrawTool(boolean onlyIfModeless) {
         if (onlyIfModeless && !MODELESS.get())
@@ -308 +321 @@
     }
 
+    /**
+     * Enables the zoom tool
+     * @param onlyIfModeless Only enable if modeless mode is active
+     * @return <code>true</code> if it is selected
+     */
     public boolean selectZoomTool(boolean onlyIfModeless) {
         if (onlyIfModeless && !MODELESS.get())
@@ -401 +419 @@
     }
 
+    /**
+     * Adds a new map mode button
+     * @param b The map mode button with a {@link MapMode} action.
+     */
     public void addMapMode(IconToggleButton b) {
         if (!(b.getAction() instanceof MapMode))
@@ -654 +676 @@
     }
 
+    /**
+     * Validate the visibility of all tool bars and hide the ones that should be hidden
+     */
     public void validateToolBarsVisibility() {
         for (IconToggleButton b : allDialogButtons) {

trunk/src/org/openstreetmap/josm/gui/MapSlider.java

@@ -15 +15 @@
 import org.openstreetmap.josm.gui.help.Helpful;
 
+/**
+ * This is the slider used in the top left corner of the map view. It allows the user to select the scale
+ */
 class MapSlider extends JSlider implements PropertyChangeListener, ChangeListener, Helpful {
 

trunk/src/org/openstreetmap/josm/gui/MapStatus.java

@@ -154 +154 @@
     }
 
+    /**
+     * The progress monitor that is used to display the progress if the user selects to run in background
+     */
     public class BackgroundProgressMonitor implements ProgressMonitorDialog {
 
@@ -225 +228 @@
     private final JProgressBar progressBar = new JProgressBar();
     private final transient ComponentAdapter mvComponentAdapter;
+    /**
+     * The progress monitor for displaying a background progress
+     */
     public final transient BackgroundProgressMonitor progressMonitor = new BackgroundProgressMonitor();
 
@@ -971 +977 @@
     }
 
+    /**
+     * Gets the panel that displays the angle
+     * @return The angle panel
+     */
     public JPanel getAnglePanel() {
         return angleText;
@@ -986 +996 @@
     }
 
-    public void setHelpText(String t) {
-        setHelpText(null, t);
-    }
-
+    /**
+     * Sets the help text in the status panel
+     * @param text The text
+     */
+    public void setHelpText(String text) {
+        setHelpText(null, text);
+    }
+
+    /**
+     * Sets the help status text to display
+     * @param id The object that caused the status update (or a id object it selects). May be <code>null</code>
+     * @param text The text
+     */
     public void setHelpText(Object id, final String text) {
-
         StatusTextHistory entry = new StatusTextHistory(id, text);
 
@@ -1003 +1021 @@
     }
 
+    /**
+     * Removes a help text and restores the previous one
+     * @param id The id passed to {@link #setHelpText(Object, String)}
+     */
     public void resetHelpText(Object id) {
         if (statusText.isEmpty())
@@ -1019 +1041 @@
     }
 
+    /**
+     * Sets the angle to display in the angle panel
+     * @param a The angle
+     */
     public void setAngle(double a) {
         angleText.setText(a < 0 ? "--" : DECIMAL_FORMAT.format(a) + " \u00B0");
     }
 
+    /**
+     * Sets the heading to display in the heading panel
+     * @param h The heading
+     */
     public void setHeading(double h) {
         headingText.setText(h < 0 ? "--" : DECIMAL_FORMAT.format(h) + " \u00B0");

trunk/src/org/openstreetmap/josm/gui/MapView.java

@@ -396 +396 @@
     private boolean virtualNodesEnabled;
 
+    /**
+     * Enables or disables drawing of the virtual nodes.
+     * @param enabled if virtual nodes are enabled
+     */
     public void setVirtualNodesEnabled(boolean enabled) {
         if (virtualNodesEnabled != enabled) {

trunk/src/org/openstreetmap/josm/gui/NameFormatterHook.java

@@ -6 +6 @@
 import org.openstreetmap.josm.data.osm.IWay;
 
+/**
+ * Hooks that allow correcting the name of a OSM primitive
+ * @see DefaultNameFormatter
+ */
 public interface NameFormatterHook {
 

trunk/src/org/openstreetmap/josm/gui/ScrollViewport.java

@@ -31 +31 @@
     private static final int NO_SCROLL = 0;
 
+    /**
+     * Direction flag for upwards
+     */
     public static final int UP_DIRECTION = 1;
+    /**
+     * Direction flag for downwards
+     */
     public static final int DOWN_DIRECTION = 2;
+    /**
+     * Direction flag for left
+     */
     public static final int LEFT_DIRECTION = 4;
+    /**
+     * Direction flag for right
+     */
     public static final int RIGHT_DIRECTION = 8;
     /**
@@ -240 +252 @@
     }
 
+    /**
+     * Gets the current visible part of the view
+     * @return The current view rect
+     */
     public Rectangle getViewRect() {
         return vp.getViewRect();
     }
 
+    /**
+     * Gets the size of the view
+     * @return The size
+     */
     public Dimension getViewSize() {
         return vp.getViewSize();
     }
 
+    /**
+     * Gets the position (offset) of the view area
+     * @return The offset
+     */
     public Point getViewPosition() {
         return vp.getViewPosition();

trunk/src/org/openstreetmap/josm/gui/ShowHideButtonListener.java

@@ -8 +8 @@
  */
 public interface ShowHideButtonListener {
+    /**
+     * Called when the button is shown
+     */
     void buttonShown();
 
+    /**
+     * Called when the button is hidden
+     */
     void buttonHidden();
 }