From 7bff0256260eaa8d9ed14cd8b77bcca2fbbfa6c7 Mon Sep 17 00:00:00 2001 From: Brian Matzon Date: Mon, 10 Feb 2003 23:09:54 +0000 Subject: [PATCH] formatting and better javadoc --- src/java/org/lwjgl/Display.java | 64 ++++++++++++++-------- src/java/org/lwjgl/DisplayMode.java | 23 +++++--- src/java/org/lwjgl/input/Controller.java | 68 ++++++++++++++---------- src/java/org/lwjgl/input/Mouse.java | 12 +++-- 4 files changed, 108 insertions(+), 59 deletions(-) diff --git a/src/java/org/lwjgl/Display.java b/src/java/org/lwjgl/Display.java index e35680a6..01ca1575 100644 --- a/src/java/org/lwjgl/Display.java +++ b/src/java/org/lwjgl/Display.java @@ -54,13 +54,13 @@ public final class Display { /** The current display mode, if created */ private static DisplayMode mode; - + /** A pointer to the native display window. On Windows this will be an hWnd. */ private static int handle; - - /** Whether or not the display has been requested to shutdown by the user */ - private static boolean closeRequested = false; - + + /** Whether or not the display has been requested to shutdown by the user */ + private static boolean closeRequested = false; + /** * No construction allowed. */ @@ -95,8 +95,9 @@ public final class Display { String title) throws Exception { - if (created) + if (created) { return; + } if (!nCreate(displayMode.width, displayMode.height, @@ -106,8 +107,9 @@ public final class Display { displayMode.depth, displayMode.stencil, fullscreen, - title)) + title)) { throw new Exception("Failed to set display mode to " + displayMode); + } created = true; mode = displayMode; @@ -135,19 +137,23 @@ public final class Display { * been created no action is taken. */ public static void destroy() { - if (!created) + if (!created) { return; + } + nDestroy(); created = false; mode = null; } - + /** * Native method to destroy the display. This will reset the handle. */ private static native void nDestroy(); /** + * Retrieves the width of the created display + * * @return the current display width. * @throws AssertionError if the display has not been created yet. */ @@ -157,6 +163,8 @@ public final class Display { } /** + * Retrieves the height of the created display + * * @return the current display height. * @throws AssertionError if the display has not been created yet. */ @@ -166,6 +174,8 @@ public final class Display { } /** + * Retrieves the current display depth of the created display + * * @return the current display depth. * @throws AssertionError if the display has not been created yet. */ @@ -175,6 +185,8 @@ public final class Display { } /** + * Retrieves the current display frequency of the created display + * * @return the current display frequency. * @throws AssertionError if the display has not been created yet. */ @@ -182,8 +194,11 @@ public final class Display { assert created : "The display has not been created yet."; return mode.freq; } - + /** + * Retrieves the DisplayMode that the display has currently been + * set to. + * * @return the current display mode, or null if the display is not yet created * @throws AssertionError if the display has not been created yet. */ @@ -191,8 +206,10 @@ public final class Display { assert created : "The display has not been created yet."; return mode; } - + /** + * Retrieves the native handle to the created window + * * @return the native handle * @throws AssertionError if the display has not been created yet. */ @@ -200,8 +217,10 @@ public final class Display { assert created : "The display has not been created yet."; return handle; } - + /** + * Tests whether or not the display has been created + * * @return true if the display has been created */ public static boolean isCreated() { @@ -217,13 +236,16 @@ public final class Display { * @return true if the display is minimized */ public static native boolean isMinimized(); - - /** - * Determines if the user has requested that the application should close. - * - * @return true if the user has requested that the application should close - */ - public static boolean isCloseRequested() { - return closeRequested; - } + + /** + * Determines if the user has requested that the application should close. + * When a user has requested that the application should shutdown, it is up to + * the application to perform the actual shutdown and cleanup of any allocated + * resources. + * + * @return true if the user has requested that the application should close + */ + public static boolean isCloseRequested() { + return closeRequested; + } } \ No newline at end of file diff --git a/src/java/org/lwjgl/DisplayMode.java b/src/java/org/lwjgl/DisplayMode.java index 52cb4670..2768d7c5 100644 --- a/src/java/org/lwjgl/DisplayMode.java +++ b/src/java/org/lwjgl/DisplayMode.java @@ -35,7 +35,9 @@ package org.lwjgl; /** * $Id$ * - * Describes a display mode. + * This class encapsulates the properties for a given display mode. + * This class is not instantiable, and is aquired from the Display. + * getAvailableDisplayModes() method. * * @author cix_foo * @version $Revision$ @@ -43,6 +45,7 @@ package org.lwjgl; public final class DisplayMode { + /** properties of the display mode */ public final int width, height, bpp, freq, alpha, depth, stencil; /** @@ -61,12 +64,15 @@ public final class DisplayMode { } - /* (non-Javadoc) + /** + * Tests for DisplayMode equality + * * @see java.lang.Object#equals(Object) */ public boolean equals(Object obj) { - if (obj == null || !(obj instanceof DisplayMode)) + if (obj == null || !(obj instanceof DisplayMode)) { return false; + } DisplayMode dm = (DisplayMode) obj; return dm.width == width @@ -78,14 +84,18 @@ public final class DisplayMode { && dm.stencil == stencil; } - /* (non-Javadoc) + /** + * Retrieves the hashcode for this object + * * @see java.lang.Object#hashCode() */ public int hashCode() { return width ^ height ^ freq ^ bpp ^ alpha ^ (depth << 8) ^ (stencil << 24); } - /* (non-Javadoc) + /** + * Retrieves a String representation of this DisplayMode + * * @see java.lang.Object#toString() */ public String toString() { @@ -106,5 +116,4 @@ public final class DisplayMode { sb.append("bit stencil"); return sb.toString(); } - -} +} \ No newline at end of file diff --git a/src/java/org/lwjgl/input/Controller.java b/src/java/org/lwjgl/input/Controller.java index fbf4440b..82e11be9 100644 --- a/src/java/org/lwjgl/input/Controller.java +++ b/src/java/org/lwjgl/input/Controller.java @@ -43,10 +43,8 @@ import org.lwjgl.Sys; * * No buffering is available. * - * Currently n (native limits, currently 128 - might change) buttons, the x, y, - * z axis is supported along with a POV (or HAT) and a slider, where the z axis - * represents a throttle. In the future the controller may support more buttons - * and axises and other features. but this is a platform issue. + * Currently n (native limits) buttons, the x, y, z axis (also rotational x,y , + * z axis) is supported along with a POV (or HAT) and a slider * * The Controller implementation currently only supports the first attached device. * @@ -67,27 +65,27 @@ public class Controller { /** X position, range -1000 to 1000 */ public static int x = 0; - - /** X rotational position, range -1000 to 1000 */ - public static int rx = 0; - + + /** X rotational position, range -1000 to 1000 */ + public static int rx = 0; + /** Y position, range -1000 to 1000 */ public static int y = 0; - - /** Y rotational position, range -1000 to 1000 */ - public static int ry = 0; - + + /** Y rotational position, range -1000 to 1000 */ + public static int ry = 0; + /** Z position, range -1000 to 1000 */ public static int z = 0; - /** Z rotational position, range -1000 to 1000 */ - public static int rz = 0; + /** Z rotational position, range -1000 to 1000 */ + public static int rz = 0; /** Position of Point of View from -1 to 27000 (360 degrees) */ public static int pov; - - /** Slider position, range -1000 to 1000 */ - public static int slider = 0; + + /** Slider position, range -1000 to 1000 */ + public static int slider = 0; /** Constant specifying centered POV */ public static final int POV_CENTER = -1; @@ -104,16 +102,32 @@ public class Controller { /** Constant specifying westward POV */ public static final int POV_WEST = 9000; - /* Controller capabilities */ + /** Number of buttons on the controller */ public static int buttonCount = -1; - public static boolean hasXAxis = false; - public static boolean hasRXAxis = false; - public static boolean hasYAxis = false; - public static boolean hasRYAxis = false; - public static boolean hasZAxis = false; - public static boolean hasRZAxis = false; + + /** Does this controller support a x axis */ + public static boolean hasXAxis = false; + + /** Does this controller support a rotational x axis */ + public static boolean hasRXAxis = false; + + /** Does this controller support an y axis */ + public static boolean hasYAxis = false; + + /** Does this controller support a rotational y axis */ + public static boolean hasRYAxis = false; + + /** Does this controller support a z axis */ + public static boolean hasZAxis = false; + + /** Does this controller support a rotational z axis */ + public static boolean hasRZAxis = false; + + /** Does this controller support a Point-Of-View (hat) */ public static boolean hasPOV = false; - public static boolean hasSlider = false; + + /** Does this controller support a slider */ + public static boolean hasSlider = false; /** * Controller cannot be constructed. @@ -165,9 +179,9 @@ public class Controller { } /** - * See if a particular button is down. + * Tests if a particular button is down. * - * @param button The index of the button you wish to test (0..buttonCount) + * @param button The index of the button you wish to test (0..buttonCount-1) * @return true if the specified button is down * @see #buttonCount */ diff --git a/src/java/org/lwjgl/input/Mouse.java b/src/java/org/lwjgl/input/Mouse.java index 08364700..23adfc5a 100644 --- a/src/java/org/lwjgl/input/Mouse.java +++ b/src/java/org/lwjgl/input/Mouse.java @@ -41,8 +41,9 @@ import org.lwjgl.Sys; * A raw Mouse interface. This can be used to poll the current state of the * mouse buttons, and determine the mouse movement delta since the last poll. * - * Up to 8 buttons are available. A scrolly wheel, if present, is the z - * value. This will be in the range of -10000 to +10000. + * n buttons supported, n being a native limit. A scrolly wheel is also + * supported, if one such is available. All movement is reported as delta from + * last position. * * @author cix_foo * @version $Revision$ @@ -68,8 +69,10 @@ public class Mouse { /** Delta Z */ public static int dwheel; - /* Mouse capabilities */ + /** Number of buttons supported by the mouse */ public static int buttonCount = -1; + + /** Does this mouse support a scroll wheel */ public static boolean hasWheel = false; /** @@ -93,6 +96,7 @@ public class Mouse { /** * "Create" the mouse. The display must first have been created. + * * @throws Exception if the mouse could not be created for any reason */ public static void create() throws Exception { @@ -143,7 +147,7 @@ public class Mouse { /** * See if a particular mouse button is down. * - * @param button The index of the button you wish to test (0..buttonCount) + * @param button The index of the button you wish to test (0..buttonCount-1) * @return true if the specified button is down */ public static boolean isButtonDown(int button) {