changeset 7432:cfdd4005b555

[DOCS] RT-35308: [Monocle] Make sure all methods in Monocle used by the X11 port have javadocs Partial fix
author Daniel Blaukopf <daniel.blaukopf@oracle.com>
date Sun, 06 Jul 2014 15:49:28 +0300
parents 9a14dd8d9f7d
children 8aa4a19308e6
files modules/graphics/src/main/java/com/sun/glass/ui/monocle/C.java modules/graphics/src/main/java/com/sun/glass/ui/monocle/InputDevice.java modules/graphics/src/main/java/com/sun/glass/ui/monocle/KeyInput.java modules/graphics/src/main/java/com/sun/glass/ui/monocle/KeyState.java modules/graphics/src/main/java/com/sun/glass/ui/monocle/LinuxKeyBits.java modules/graphics/src/main/java/com/sun/glass/ui/monocle/LinuxSystem.java modules/graphics/src/main/java/com/sun/glass/ui/monocle/MouseInput.java modules/graphics/src/main/java/com/sun/glass/ui/monocle/MouseState.java modules/graphics/src/main/java/com/sun/glass/ui/monocle/NativeCursor.java modules/graphics/src/main/java/com/sun/glass/ui/monocle/NullCursor.java modules/graphics/src/main/java/com/sun/glass/ui/monocle/SoftwareCursor.java modules/graphics/src/main/java/com/sun/glass/ui/monocle/TouchState.java
diffstat 12 files changed, 341 insertions(+), 4 deletions(-) [+]
line wrap: on
line diff
--- a/modules/graphics/src/main/java/com/sun/glass/ui/monocle/C.java	Sun Jul 06 13:07:54 2014 +0300
+++ b/modules/graphics/src/main/java/com/sun/glass/ui/monocle/C.java	Sun Jul 06 15:49:28 2014 +0300
@@ -28,12 +28,23 @@
 import java.nio.ByteBuffer;
 import java.security.Permission;
 
+/**
+ * The C class provides ways to wrap pointers to native C structures in Java
+ * objects.
+ *
+ * C is a singleton. Its instance is obtained by calling C.getC(). This
+ * requires the RuntimePermission "loadLibrary.*".
+ */
 class C {
 
     private static Permission permission = new RuntimePermission("loadLibrary.*");
 
     private static C instance = new C();
 
+    /**
+     * Obtains the single instance of LinuxSystem. Calling this method requires
+     * the RuntimePermission "loadLibrary.*".
+     */
     static C getC() {
         checkPermissions();
         return instance;
@@ -49,21 +60,51 @@
     private C() {
     }
 
+    /**
+     * Structure is used for wrapping C structs in Java objects. A subclass of
+     * Structure must implement the method sizeof() to define the size of the
+     * struct it wraps.
+     */
     static abstract class Structure {
         final ByteBuffer b;
         final long p;
+
+        /** Create a new Structure wrapping a new C struct */
         protected Structure() {
             b = ByteBuffer.allocateDirect(sizeof());
             p = getC().GetDirectBufferAddress(b);
         }
+
+        /**
+         * Create a new Structure wrapping the C struct at the given location
+         * in memory
+         * @param ptr The memory address of the C struct to wrap
+         */
         protected Structure(long ptr) {
             b = getC().NewDirectByteBuffer(ptr, sizeof());
             p = ptr;
         }
+
+        /** The size of the C struct in bytes. Must be overridden by subclasses. */
         abstract int sizeof();
     }
 
+    /** Create a new ByteBuffer that provides access to the memory at a given
+     *  address
+     *
+     * @param ptr The memory address for which to create a ByteBuffer.
+     * @param size The byte length of memory to be wrapped in the ByteBuffer.
+     * @return a new ByteBuffer providing direct access to the requested
+     * memory region
+     */
     native ByteBuffer NewDirectByteBuffer(long ptr, int size);
+
+    /**
+     * Finds the memory address pointed to by a direct ByteBuffer
+     *
+     * @param b a direct ByteBuffer
+     * @return the memory address referenced by b
+     */
     native long GetDirectBufferAddress(ByteBuffer b);
 
 }
--- a/modules/graphics/src/main/java/com/sun/glass/ui/monocle/InputDevice.java	Sun Jul 06 13:07:54 2014 +0300
+++ b/modules/graphics/src/main/java/com/sun/glass/ui/monocle/InputDevice.java	Sun Jul 06 15:49:28 2014 +0300
@@ -25,12 +25,43 @@
 
 package com.sun.glass.ui.monocle;
 
+/**
+ * Abstraction of an input device and its capabilities
+ */
 interface InputDevice {
 
+    /**
+     * @return true if the device provides touch input for at least one touch
+     * point.
+     */
     boolean isTouch();
+
+    /**
+     * @return true if the device provides touch input for more than one touch
+     * point.
+     */
     boolean isMultiTouch();
+
+    /**
+     * @return true if the device provides relative pointing events. Relative
+     * pointing events are those received from devices where the event signifies
+     * a relative change in cursor position on the screen. For example, a mouse,
+     * trackball, trackpad or joystick is a relative pointing device. A touch
+     * screen is an sbsolute pointing device.
+     */
     boolean isRelative();
+
+    /**
+     * @return true if the device provides direction arrow keys (UP, DOWN, LEFT
+     * and RIGHT) and a selection key.
+     */
     boolean is5Way();
+
+    /**
+     * @return true if the device provides keys for the letters 'A' through 'Z',
+     * the digits '0' through '9' and also SPACE, SHIFT and TAB keys in addition
+     * to directional arrows and a selection key.
+     */
     boolean isFullKeyboard();
 
 }
--- a/modules/graphics/src/main/java/com/sun/glass/ui/monocle/KeyInput.java	Sun Jul 06 13:07:54 2014 +0300
+++ b/modules/graphics/src/main/java/com/sun/glass/ui/monocle/KeyInput.java	Sun Jul 06 15:49:28 2014 +0300
@@ -48,10 +48,19 @@
         return instance;
     }
 
+    /** Copies the current state into the KeyState provided.
+     *
+     * @param result target into which to copy the key state
+     */
     void getState(KeyState result) {
         state.copyTo(result);
     }
 
+    /** Called from the input processor to update the key state and send
+     * key events.
+     *
+     * @param newState The updated key state
+     */
     void setState(KeyState newState) {
         if (MonocleSettings.settings.traceEvents) {
             MonocleTrace.traceEvent("Set %s", newState);
--- a/modules/graphics/src/main/java/com/sun/glass/ui/monocle/KeyState.java	Sun Jul 06 13:07:54 2014 +0300
+++ b/modules/graphics/src/main/java/com/sun/glass/ui/monocle/KeyState.java	Sun Jul 06 15:49:28 2014 +0300
@@ -27,33 +27,49 @@
 
 import com.sun.glass.events.KeyEvent;
 
+/**
+ * KeyState is a snapshot of pressed keys
+ * KeyState is used both to store the current state of key input and to
+ * describe changes to that state.
+ */
 class KeyState {
 
     private IntSet keysPressed = new IntSet();
     private MonocleWindow window;
     private int modifiers;
 
+    /** Removes all pressed keys from this state object. */
     void clear() {
         keysPressed.clear();
         modifiers = 0;
     }
 
+    /** Adds a key to the set of pressed keys. */
     void pressKey(int virtualKeyCode) {
         keysPressed.addInt(virtualKeyCode);
         modifiers |= getModifier(virtualKeyCode);
     }
 
+    /** Removes a key from the set of pressed keys. */
     void releaseKey(int virtualKeyCode) {
         keysPressed.removeInt(virtualKeyCode);
         modifiers &= ~getModifier(virtualKeyCode);
     }
 
+    /** Copies the contents of this state object to another.
+     *
+     * @param target The KeyState to which to copy this state's data.
+     */
     void copyTo(KeyState target) {
         keysPressed.copyTo(target.keysPressed);
         target.window = window;
         target.modifiers = modifiers;
     }
 
+    /** Returns the set of pressed key codes
+     *
+     * @return an IntSet containing the key codes of pressed keys
+     */
     IntSet getKeysPressed() {
         return keysPressed;
     }
@@ -78,6 +94,11 @@
         }
     }
 
+    /** Returns a mask of modifiers defined in KeyEvent for the keys pressed
+     * in this state.
+     *
+     * @return a mask of KeyEvent modifiers
+     */
     int getModifiers() {
         return modifiers;
     }
--- a/modules/graphics/src/main/java/com/sun/glass/ui/monocle/LinuxKeyBits.java	Sun Jul 06 13:07:54 2014 +0300
+++ b/modules/graphics/src/main/java/com/sun/glass/ui/monocle/LinuxKeyBits.java	Sun Jul 06 15:49:28 2014 +0300
@@ -45,7 +45,7 @@
         KEY_K, KEY_L, KEY_M, KEY_N, KEY_O, KEY_P, KEY_Q, KEY_R, KEY_S, KEY_T,
         KEY_U, KEY_V, KEY_W, KEY_X, KEY_Y, KEY_Z,
         KEY_1, KEY_2, KEY_3, KEY_4, KEY_5, KEY_6, KEY_7, KEY_8, KEY_9, KEY_0,
-        KEY_LEFTSHIFT, KEY_TAB
+        KEY_SPACE, KEY_LEFTSHIFT, KEY_TAB
     };
 
 }
--- a/modules/graphics/src/main/java/com/sun/glass/ui/monocle/LinuxSystem.java	Sun Jul 06 13:07:54 2014 +0300
+++ b/modules/graphics/src/main/java/com/sun/glass/ui/monocle/LinuxSystem.java	Sun Jul 06 15:49:28 2014 +0300
@@ -30,11 +30,27 @@
 import java.nio.ByteBuffer;
 import java.security.Permission;
 
+/**
+ * LinuxSystem provides access to Linux system calls. Except where noted, each
+ * method in LinuxSystem corresponds to exactly one system call taking
+ * parameters in the same order and returning the same result as the
+ * corresponding C function.
+ *
+ * LinuxSystem is a singleton. Its instance is obtained by calling
+ * LinuxSystem.getLinuxSystem().
+ */
 class LinuxSystem {
     private static Permission permission = new RuntimePermission("loadLibrary.*");
 
     private static LinuxSystem instance = new LinuxSystem();
 
+    /**
+     * Obtains the single instance of LinuxSystem. Calling this method requires
+     * the RuntimePermission "loadLibrary.*".
+     *
+     * loadLibrary() must be called on the LinuxSystem instance before any
+     * system calls can be made using it.
+     */
     static LinuxSystem getLinuxSystem() {
         checkPermissions();
         return instance;
@@ -50,6 +66,12 @@
     private LinuxSystem() {
     }
 
+    /**
+     * Loads native libraries required to make system calls using LinuxSystem
+     * methods. This method must be called before any other instance methods of
+     * LinuxSystem. If this method is called multiple times, it has no effect
+     * after the first call.
+     */
     void loadLibrary() {
         NativeLibLoader.loadLibrary("glass_monocle");
     }
@@ -69,21 +91,84 @@
     // unistd.h
     native int close(long fd);
     native long lseek(long fd, long offset, int whence);
+
+    /**
+     * Calls the "write" function defined in unistd.h. The parameters have
+     * the same meaning as in the "write" C system call,
+     * except that a ByteBuffer with a position and limit are used for the
+     * source data. The position and limit set on the ByteBuffer are ignored;
+     * the position and limit provided as method parameters are used instead.
+     * @param fd The file descriptor to which to write
+     * @param buf The buffer from which to write
+     * @param position The index in buf of the first byte to write
+     * @param limit The index in buf up to which to write
+     * @return The number of bytes written, or -1 on failure
+     */
     native long write(long fd, ByteBuffer buf, int position, int limit);
+
+    /**
+     * Calls the "read" function defined in unistd.h. The parameters have
+     * the same meaning as in the "read" C system call,
+     * except that a ByteBuffer with a position and limit are used for the
+     * data sink. The position and limit set on the ByteBuffer are ignored;
+     * the position and limit provided as method parameters are used instead.
+     * @param fd The file descriptor from which to read
+     * @param buf The buffer to which to write
+     * @param position The index in buf to which to being reading data
+     * @param limit The index in buf up to which to read data
+     * @return The number of bytes read, or -1 on failure
+     */
     native long read(long fd, ByteBuffer buf, int position, int limit);
 
     static final int SEEK_SET = 0;
 
     // input.h
 
+    /**
+     * InputAbsInfo wraps the C structure input_absinfo, defined in
+     * linux/input.h
+     */
     static class InputAbsInfo extends C.Structure {
+        /**
+         * @return the size of the C struct input_absinfo
+         */
         @Override
         native int sizeof();
+
+        /**
+         * @param p a pointer to a C struct of type input_absinfo
+         * @return the "value" field of the structure pointed to by p
+         */
         static native int getValue(long p);
+
+        /**
+         * @param p a pointer to a C struct of type input_absinfo
+         * @return the "minimum" field of the structure pointed to by p
+         */
         static native int getMinimum(long p);
+
+        /**
+         * @param p a pointer to a C struct of type input_absinfo
+         * @return the "maximum" field of the structure pointed to by p
+         */
         static native int getMaximum(long p);
+
+        /**
+         * @param p a pointer to a C struct of type input_absinfo
+         * @return the "fuzz" field of the structure pointed to by p
+         */
         static native int getFuzz(long p);
+
+        /**
+         * @param p a pointer to a C struct of type input_absinfo
+         * @return the "flat" field of the structure pointed to by p
+         */
         static native int getFlat(long p);
+
+        /**
+         * @param p a pointer to a C struct of type input_absinfo
+         * @return the "resolution" field of the structure pointed to by p
+         */
         static native int getResolution(long p);
     }
 
@@ -100,6 +185,10 @@
     static final int FB_ACTIVATE_NOW = 0;
     static final int FB_ACTIVATE_VBL = 16;
 
+    /**
+     * FbVarScreenInfo wraps the C structure fb_var_screeninfo, defined in
+     * linux/fb.h
+     */
     static class FbVarScreenInfo extends C.Structure {
         FbVarScreenInfo() {
             checkPermissions();
@@ -168,6 +257,9 @@
     // string.h
     native long memcpy(long destAddr, long srcAddr, long length);
 
+    /** Returns a string description of the last error reported by a system call
+     * @return a String describing the error
+     */
     String getErrorMessage() {
         return strerror(errno());
     }
--- a/modules/graphics/src/main/java/com/sun/glass/ui/monocle/MouseInput.java	Sun Jul 06 13:07:54 2014 +0300
+++ b/modules/graphics/src/main/java/com/sun/glass/ui/monocle/MouseInput.java	Sun Jul 06 15:49:28 2014 +0300
@@ -33,7 +33,7 @@
 
 /**
  * Processes mouse input events based on changes to mouse state. Not
- * thread-safe.
+ * thread-safe and can only be used on the JavaFX application thread.
  */
 class MouseInput {
     private static MouseInput instance = new MouseInput();
@@ -58,10 +58,25 @@
         return instance;
     }
 
+    /** Retrieves the current state of mouse buttons and of the cursor.
+     *
+     * @param result a MouseState to which to copy data on the current mouse
+     *               buttons and coordinates.
+     */
     void getState(MouseState result) {
         state.copyTo(result);
     }
 
+    /**
+     * Sets a new state for mouse buttons and coordinates, generating input
+     * events where appropriate.
+     *
+     * @param newState    the new state
+     * @param synthesized true if this state change is synthesized from a change
+     *                    in touch state; false if this state change comes from
+     *                    an actual relative pointing devices or from the Glass
+     *                    robot.
+     */
     void setState(MouseState newState, boolean synthesized) {
         if (MonocleSettings.settings.traceEvents) {
             MonocleTrace.traceEvent("Set %s", newState);
--- a/modules/graphics/src/main/java/com/sun/glass/ui/monocle/MouseState.java	Sun Jul 06 13:07:54 2014 +0300
+++ b/modules/graphics/src/main/java/com/sun/glass/ui/monocle/MouseState.java	Sun Jul 06 15:49:28 2014 +0300
@@ -28,6 +28,11 @@
 import com.sun.glass.events.KeyEvent;
 import com.sun.glass.events.MouseEvent;
 
+/**
+ * MouseState is a snapshot of mouse coordinates and which buttons are pressed.
+ * MouseState is used both to store the current state of mouse input and to
+ * describe changes to that state.
+ */
 class MouseState {
 
     static final int WHEEL_NONE = 0;
@@ -73,7 +78,14 @@
         buttonsPressed.removeInt(button);
     }
 
-    /** Returns the Glass window on which this event state is located . */
+    /** Returns the Glass window on which the coordinates of this state are located.
+     * @param recalculateCache true if the cached value for the target window
+     *                         should be recalculated; false if the cached
+     *                         value should be used to determine the result
+     *                         of this method.
+     * @return the MonocleWindow at the top of the stack at the coordinates
+     * described by this state object.
+     */
     MonocleWindow getWindow(boolean recalculateCache) {
         if (window == null || recalculateCache) {
             window = (MonocleWindow)
@@ -108,6 +120,10 @@
         return modifiers;
     }
 
+    /** Copies the contents of this state object to another.
+     *
+     * @param target The MouseState to which to copy this state's data.
+     */
     void copyTo(MouseState target) {
         target.x = x;
         target.y = y;
--- a/modules/graphics/src/main/java/com/sun/glass/ui/monocle/NativeCursor.java	Sun Jul 06 13:07:54 2014 +0300
+++ b/modules/graphics/src/main/java/com/sun/glass/ui/monocle/NativeCursor.java	Sun Jul 06 15:49:28 2014 +0300
@@ -27,24 +27,66 @@
 
 import com.sun.glass.ui.Size;
 
+/**
+ * Abstraction of a native cursor
+ */
 abstract class NativeCursor {
 
+    /**
+     * Is the cursor currently visible?
+     */
     protected boolean isVisible = false;
 
+    /**
+     * Returns the preferred size of a native cursor.
+     */
     abstract Size getBestSize();
 
-    // setVisibility can fail silently; use getVisibility to check the results
+    /**
+     * Sets whether or not the cursor is visible. The implementation should set
+     * the isVisible field. On success the isVisible field is set to the
+     * visibility parameter.
+     *
+     * @param visibility the new setting for the cursor's visibility.
+     */
     abstract void setVisibility(boolean visibility);
 
+    /**
+     * Queries whether or not the cursor is visible
+     *
+     * @return trueif the cursor is visible, false otherwise.
+     */
     boolean getVisiblity() {
         return isVisible;
     }
 
+    /**
+     * Sets the cursor image
+     *
+     * @param cursorImage the cursor image, in BYTE_BGRA_PRE format
+     */
     abstract void setImage(byte[] cursorImage);
 
+    /**
+     * Sets the location of the hot spot of the cursor on the screen
+     *
+     * @param x the new X location on the screen
+     * @param y the new Y location on the screen
+     */
     abstract void setLocation(int x, int y);
 
+    /**
+     * Sets the offset of the cursor's hot spot within the cursor image The hot
+     * spot offsets default to 0, 0.
+     *
+     * @param hotspotX the X offset of the hot spot
+     * @param hotspotY the Y offset of the hot spot.
+     */
     abstract void setHotSpot(int hotspotX, int hotspotY);
 
+    /**
+     * Performs any necessary shutdown of the cursor infrastructure. Called only
+     * once.
+     */
     abstract void shutdown();
 }
--- a/modules/graphics/src/main/java/com/sun/glass/ui/monocle/NullCursor.java	Sun Jul 06 13:07:54 2014 +0300
+++ b/modules/graphics/src/main/java/com/sun/glass/ui/monocle/NullCursor.java	Sun Jul 06 15:49:28 2014 +0300
@@ -27,6 +27,10 @@
 
 import com.sun.glass.ui.Size;
 
+/**
+ * Provides an implementation of NativeCursor that does nothing and does not
+ * show a cursor on the screen.
+ */
 class NullCursor extends NativeCursor {
 
     @Override
--- a/modules/graphics/src/main/java/com/sun/glass/ui/monocle/SoftwareCursor.java	Sun Jul 06 13:07:54 2014 +0300
+++ b/modules/graphics/src/main/java/com/sun/glass/ui/monocle/SoftwareCursor.java	Sun Jul 06 15:49:28 2014 +0300
@@ -31,6 +31,10 @@
 import java.nio.ByteBuffer;
 import java.nio.ByteOrder;
 
+/**
+ * Provides an implementation of NativeCursor that overlays a cursor image on
+ * top of a software-rendered framebuffer.
+ */
 class SoftwareCursor extends NativeCursor {
 
     private ByteBuffer cursorBuffer;
--- a/modules/graphics/src/main/java/com/sun/glass/ui/monocle/TouchState.java	Sun Jul 06 13:07:54 2014 +0300
+++ b/modules/graphics/src/main/java/com/sun/glass/ui/monocle/TouchState.java	Sun Jul 06 15:49:28 2014 +0300
@@ -25,15 +25,35 @@
 
 package com.sun.glass.ui.monocle;
 
+import org.eclipse.swt.internal.cocoa.id;
+
 import java.util.Arrays;
 import java.util.Comparator;
 
+/**
+ * TouchState is a snapshot of touch points and their coordinates.
+ * TouchState is used both to store the current state of touch input and to
+ * describe changes to that state.
+ *
+ * A TouchState contains a number of Points. Each point has a unique ID,
+ * which is either assigned by a touch driver, or by JavaFX's input
+ * processing code. One touch point is defined as the primary touch point; it
+ * is this touch point's coordinates that are used to determine the
+ * coordinates of synthesized mouse events.
+ */
 class TouchState {
 
+    /** Describes a single touch point */
     static class Point {
         int id;
         int x;
         int y;
+
+        /**
+         * Copies a touch point's data to a target Point
+         *
+         * @param target the Point object to which to copy this object's data
+         */
         void copyTo(Point target) {
             target.id = id;
             target.x = x;
@@ -77,6 +97,13 @@
         return window;
     }
 
+    /**
+     * Returns the nth point in the toich point list, for index n
+     *
+     * @param index The index of the point point to return. index should be less
+     *              than the value returned by getPointCount().
+     * @return A touch point.
+     */
     Point getPoint(int index) {
         return points[index];
     }
@@ -94,10 +121,12 @@
         return null;
     }
 
+    /** Returns the touch point ID of the primary point. */
     int getPrimaryID() {
         return primaryID;
     }
 
+    /** Updates the primary point ID */
     void assignPrimaryID() {
         if (pointCount == 0) {
             primaryID = -1;
@@ -116,14 +145,29 @@
         }
     }
 
+    /** Returns the number of touch points pressed.
+     *
+     * @return the number of touch points
+     */
     int getPointCount() {
         return pointCount;
     }
 
+    /** Removes all touch points from this state. */
     void clear() {
         pointCount = 0;
     }
 
+    /** Adds a Point to this state object.
+     *
+     * @param p the Point describing the data to add, or null if no data is
+     *          available yet for this point. p is not modified,
+     *          but its contents are copied to the object describing the new
+     *          Point.
+     * @return the Point with the data for the new touch point. The fields of
+     * this Point may be modified directly to change the data for the new
+     * touch point.
+     */
     Point addPoint(Point p) {
         if (points.length == pointCount) {
             points = Arrays.copyOf(points, points.length * 2);
@@ -137,6 +181,10 @@
         return points[pointCount++];
     }
 
+    /** Removes the point with the given ID
+     *
+     * @param id The ID of the touch point which is to be removed.
+     */
     void removePointForID(int id) {
         for (int i = 0; i < pointCount; i++) {
             if (points[i].id == id) {
@@ -149,6 +197,12 @@
         }
     }
 
+    /** Replaces the touch point data at the given index with the given touch
+     *    point data
+     *
+     * @param index the index at which to change the touch point data
+     * @param p the data to copy to the given index.
+     */
     void setPoint(int index, Point p) {
         if (index >= pointCount) {
             throw new IndexOutOfBoundsException();
@@ -156,6 +210,10 @@
         p.copyTo(points[index]);
     }
 
+    /** Copies the contents of this state object to another.
+     *
+     * @param target The TouchState to which to copy this state's data.
+     */
     void copyTo(TouchState target) {
         target.clear();
         for (int i = 0; i < pointCount; i++) {
@@ -176,6 +234,10 @@
         return sb.toString();
     }
 
+    /**
+     * Modifies the ordering touch points in this state object so that the
+     * points are sorted in increasing order of ID.
+     */
     void sortPointsByID() {
         Arrays.sort(points, 0, pointCount, pointIdComparator);
     }