GNOME.org
 

java-gobject-introspection r164 - trunk/src/gobject/runtime

Author: walters
Date: Fri Jan 30 05:35:09 2009
New Revision: 164
URL: http://svn.gnome.org/viewvc/java-gobject-introspection?rev=164&view=rev

Log:
Greatly extend Javadoc for core gobject.runtime package

Added:
   trunk/src/gobject/runtime/package-info.java
Modified:
   trunk/src/gobject/runtime/AsyncReadyCallback.java
   trunk/src/gobject/runtime/AsyncResult.java
   trunk/src/gobject/runtime/BooleanByReference.java
   trunk/src/gobject/runtime/BoxedStructure.java
   trunk/src/gobject/runtime/BoxedUnion.java
   trunk/src/gobject/runtime/GBoxed.java
   trunk/src/gobject/runtime/GErrorException.java
   trunk/src/gobject/runtime/GFlags.java
   trunk/src/gobject/runtime/GInitiallyUnowned.java
   trunk/src/gobject/runtime/GObject.java
   trunk/src/gobject/runtime/GType.java
   trunk/src/gobject/runtime/GValue.java
   trunk/src/gobject/runtime/MainLoop.java

Modified: trunk/src/gobject/runtime/AsyncReadyCallback.java
==============================================================================
--- trunk/src/gobject/runtime/AsyncReadyCallback.java	(original)
+++ trunk/src/gobject/runtime/AsyncReadyCallback.java	Fri Jan 30 05:35:09 2009
@@ -6,8 +6,10 @@
 import com.sun.jna.TypeMapper;
 
 /**
- * Type definition for a function that will be called back 
- * when an asynchronous operation within GIO has been completed.
+ * A callback that will be invoked when an asynchronous operation
+ * within Gio has been completed.
+ * 
+ * @see <a href="../../gtk-doc/gio/GAsyncResult.html#GAsyncReadyCallback">native GAsyncResult</a>
  */
 public interface AsyncReadyCallback extends Callback {
 	final TypeMapper TYPE_MAPPER = GTypeMapper.getInstance();

Modified: trunk/src/gobject/runtime/AsyncResult.java
==============================================================================
--- trunk/src/gobject/runtime/AsyncResult.java	(original)
+++ trunk/src/gobject/runtime/AsyncResult.java	Fri Jan 30 05:35:09 2009
@@ -5,7 +5,9 @@
 
 
 /**
- * Provides a base class for implementing asynchronous function results. 
+ * Holds the result of an asynchronous computation.
+ * 
+ * @see <a href="../../gtk-doc/gio/GAsyncResult.html">native GAsyncResult</a>
  */
 public interface AsyncResult extends GObjectProxy {
 	public GObject getSourceObject();

Modified: trunk/src/gobject/runtime/BooleanByReference.java
==============================================================================
--- trunk/src/gobject/runtime/BooleanByReference.java	(original)
+++ trunk/src/gobject/runtime/BooleanByReference.java	Fri Jan 30 05:35:09 2009
@@ -5,8 +5,6 @@
 /**
  * A simple class for passing Boolean values by reference,
  * similar to the other JNA classes.
- * 
- * @author walters
  */
 public class BooleanByReference extends ByReference {
 

Modified: trunk/src/gobject/runtime/BoxedStructure.java
==============================================================================
--- trunk/src/gobject/runtime/BoxedStructure.java	(original)
+++ trunk/src/gobject/runtime/BoxedStructure.java	Fri Jan 30 05:35:09 2009
@@ -8,7 +8,14 @@
 import com.sun.jna.Structure;
 import com.sun.jna.TypeMapper;
 
-
+/**
+ * Peer object for a native "boxed" structure type. This class extends the 
+ * JNA { link com.sun.jna.Structure} class, and may be manipulated using methods
+ * associated with that class.
+ * 
+ * @see com.sun.jna.Structure
+ * @see <a href="../../gtk-doc/html/gobject/gobject-Boxed-Types.html">Boxed Types</a>
+ */
 public abstract class BoxedStructure extends Structure implements RegisteredType {
 
 	private final GType gtype;

Modified: trunk/src/gobject/runtime/BoxedUnion.java
==============================================================================
--- trunk/src/gobject/runtime/BoxedUnion.java	(original)
+++ trunk/src/gobject/runtime/BoxedUnion.java	Fri Jan 30 05:35:09 2009
@@ -8,7 +8,14 @@
 import com.sun.jna.TypeMapper;
 import com.sun.jna.Union;
 
-
+/**
+ * Peer object for a native "boxed" union type. This class extends the 
+ * JNA { link com.sun.jna.Union} class, and may be manipulated using methods
+ * associated with that class.
+ * 
+ * @see com.sun.jna.Union 
+ * @see <a href="../../gtk-doc/html/gobject/gobject-Boxed-Types.html">Boxed Types</a>
+ */
 public abstract class BoxedUnion extends Union implements RegisteredType {
 	
 	private final GType gtype;

Modified: trunk/src/gobject/runtime/GBoxed.java
==============================================================================
--- trunk/src/gobject/runtime/GBoxed.java	(original)
+++ trunk/src/gobject/runtime/GBoxed.java	Fri Jan 30 05:35:09 2009
@@ -12,6 +12,15 @@
 import com.sun.jna.Structure;
 import com.sun.jna.TypeMapper;
 
+/**
+ * Peer object for an <i>opaque</i> native "boxed" type.  This class is used
+ * when the boxed type is not known to be a structure or union.
+ * 
+ * Typically an instance of { code GBoxed} is just passed between native functions
+ * without manipulation from managed code.
+ * 
+ * @see <a href="../../gtk-doc/html/gobject/gobject-Boxed-Types.html">Boxed Types</a>
+ */
 public abstract class GBoxed extends PointerType implements RegisteredType {
 	
 	protected GType gtype = GType.INVALID;

Modified: trunk/src/gobject/runtime/GErrorException.java
==============================================================================
--- trunk/src/gobject/runtime/GErrorException.java	(original)
+++ trunk/src/gobject/runtime/GErrorException.java	Fri Jan 30 05:35:09 2009
@@ -25,6 +25,11 @@
 
 import gobject.internals.GErrorStruct;
 
+/**
+ * Exception thrown by native methods which use the { code GError} mechanism.
+ * 
+ * @see <a href="../../gtk-doc/html/glib/glib-Error-Reporting.html">GError</a>
+ */
 public class GErrorException extends Exception {
 	private static final long serialVersionUID = 1L;
 	private int domain;

Modified: trunk/src/gobject/runtime/GFlags.java
==============================================================================
--- trunk/src/gobject/runtime/GFlags.java	(original)
+++ trunk/src/gobject/runtime/GFlags.java	Fri Jan 30 05:35:09 2009
@@ -4,8 +4,18 @@
 import com.sun.jna.NativeMapped;
 
 /**
- * Base class for multi-valued bitfields, or flags.  Converted
- * between an integer type when passed to native code.
+ * Base class for multi-valued bitfields, or flags.  In native code,
+ * this value is represented as an integral type.
+ * <p>
+ * Each flag is represented by a constant associated with the class.  Typical
+ * usage is to create a new instance with the varargs constructor { link GFlags(int...)},
+ * passed to native code.
+ * <p>
+ * For example:
+ * <pre>
+ *   File f = GioGlobals.fileNewForPath("/home/username/Documents"); 
+ *   FileMonitor fm = f.monitorFile(new FileMonitorFlags(FileMonitorFlags.WATCH_MOUNTS), null);
+ * </pre> 
  */
 public abstract class GFlags implements NativeMapped {
 	private int value = 0;
@@ -18,6 +28,11 @@
 		this.value = value;
 	}
 	
+	/**
+	 * Create a flag object which holds the union of all specified individual flag values.
+	 * 
+	 * @param flags List of flag values
+	 */
 	public GFlags(int...flags) {
 		add(flags);
 	}
@@ -34,6 +49,10 @@
 		value &= ~val;
 	}
 	
+	/**
+	 * Returns the native integral value, i.e. the bitwise and of the individual
+	 * flag values.
+	 */	
 	public final int getValue() {
 		return value;
 	}

Modified: trunk/src/gobject/runtime/GInitiallyUnowned.java
==============================================================================
--- trunk/src/gobject/runtime/GInitiallyUnowned.java	(original)
+++ trunk/src/gobject/runtime/GInitiallyUnowned.java	Fri Jan 30 05:35:09 2009
@@ -3,6 +3,14 @@
 import java.util.Map;
 
 
+/**
+ * A kind of { link GObject} which in native code has a "floating" reference.
+ * This distinction is irrelevant to managed Java code - all GObjects have
+ * any floating references immediately "sunk".
+ * <p>
+ * @see <a href="../../gtk-doc/html/gobject/gobject-The-Base-Object-Type.html#floating-ref">floating references</a>
+ * @see <a href="../../gtk-doc/html/gobject/gobject-The-Base-Object-Type.html#GInitiallyUnowned">native GInitiallyUnowned</a>
+ */
 public abstract class GInitiallyUnowned extends GObject {
 	/*
 	 * Note - memory management for this class is handled inside GObject, we

Modified: trunk/src/gobject/runtime/GObject.java
==============================================================================
--- trunk/src/gobject/runtime/GObject.java	(original)
+++ trunk/src/gobject/runtime/GObject.java	Fri Jan 30 05:35:09 2009
@@ -67,15 +67,56 @@
 import com.sun.jna.TypeMapper;
 
 /**
- * This class provides the base Java peer for a GObject.  It should generally not
- * be necessary to call functions in this class directly, as more convenient wrapper
- * functions for e.g. property retrieval are generated by the JGIR compiler.
- * 
- * The one component which is important to understand is the fundamental constructors.
+ * Provides the base Java peer for a native <tt>GObject</tt>.
+ * <p>
+ * <h3>Constructors</h3>
  * GObject has a powerful property mechanism, and object authors can specify properties
  * which are accessible at object construction time.  This is mapped as two different
  * kinds of constructors, one which takes a Map, and one which takes an Array of pairs.
- *  
+ * <p>
+ * For example, using the array { link GObject(Object[])} constructor:
+ * <pre>
+ *   Window w = new Window(new Object[] { "type", Gtk.WindowType.TOPLEVEL, "opacity", 0.5 });
+ * </pre>
+ * <p>
+ * And, using the map { link GObject(Map)} constructor:
+ * <pre>
+ *   Window w = new Window(new HashMap<String,Object>() {
+ *     {
+ *       put("type", Gtk.WindowType.TOPLEVEL);
+ *       put("opacity", 0.5);
+ *     }
+ *   });
+ * </pre>
+ * <h3>Signals</h3>
+ * Each GObject signal is mapped to two Java components.  First, the signal signature (prototype) is exposed as
+ * a Java interface.  Second, a method named "connect" taking an instance of that interface is added to the class.
+ * <p>
+ * A typical signal connection looks like:
+ * <pre>
+ *   somewidget.connect(new Show() {
+ *     public void onShow(Widget w) {
+ *         System.err.println("Widget " + w + " is shown");
+ *     }
+ *   });
+ * </pre>
+ * <h3>Properties</h3>
+ * Each GObject property has up to 4 corresponding Java components.  If the property is readable, then
+ * a "get&lt;PropertyName&gt;" method is generated.  If the property is writable,a "set&lt;PropertyName&gt;(value)" method is generated.
+ * Finally, because GObject supports notification of property changes, in a similar fashion to signals a pair of a notification interface
+ * and connect method are generated.
+ * <p>
+ * Connecting a notification for changes of window title value, then setting it.
+ * <pre>
+ *   window.connectNotify(new TitleNotify() {
+ *     public void onTitleNotify(Window win) {
+ *         System.err.println("Title of window changed to: " + win.getTitle());
+ *     });
+ *   }
+ * 
+ *   window.setTitle("My Window");
+ * </pre>
+ * @see <a href="../../gtk-doc/html/gobject/gobject-The-Base-Object-Type.html">native GObject</a>  
  */
 public abstract class GObject extends NativeObject {
 	private static final Map<GObject, Boolean> strongReferences = new ConcurrentHashMap<GObject, Boolean>();
@@ -122,10 +163,10 @@
 	};
 
 	/**
-	 * A tagging interface used in the code generator - if a method returns an
-	 * interface, we have it extend this interface so we know it's a GObject.
+	 * A tagging interface for a native GInterface, which is exposed by JGIR as a
+	 * Java interface.
 	 * 
-	 * @author walters
+	 * @see <a href="../../gtk-doc/html/gobject/gtype-non-instantiable-classed.html">native GInterface</a>
 	 */
 	public static interface GObjectProxy {
 	};

Modified: trunk/src/gobject/runtime/GType.java
==============================================================================
--- trunk/src/gobject/runtime/GType.java	(original)
+++ trunk/src/gobject/runtime/GType.java	Fri Jan 30 05:35:09 2009
@@ -57,15 +57,14 @@
 import com.sun.jna.Pointer;
 
 /**
- * GType is the fundamental building block of GObject. It provides
- * runtime-accessible type information. GTypes can be full GObjects, or just
- * boxed integers or structures.
- * 
+ * The fundamental runtime type information of the <tt>GObject</tt> library. In native code,
+ * a GType is an opaque integral type.  All subclasses of { link GObject} and { link GBoxed} have associated
+ * native GTypes.
+ * <p>
  * This class provides an API for accessing fundamental GTypes, as well as
  * looking up the GType associated with a mapped GObject.
- * 
- * @author walters
- * 
+ * <p>
+ * @see <a href="../../gtk-doc/html/gobject/gobject-Type-Information.html">native GType</a>
  */
 public class GType extends NativeLong {
 	private static final long serialVersionUID = 1L;

Modified: trunk/src/gobject/runtime/GValue.java
==============================================================================
--- trunk/src/gobject/runtime/GValue.java	(original)
+++ trunk/src/gobject/runtime/GValue.java	Fri Jan 30 05:35:09 2009
@@ -52,8 +52,10 @@
 import com.sun.jna.Pointer;
 
 /**
- * GValue is a the native GObject concept of a "boxed" value; i.e. a pair of data
- * with metadata about its type.
+ * Managed peer representing a native { code GValue} structure.  A GValue is the pair of
+ * a value with its { link GType}.  
+ * 
+ * @see <a href="../../gtk-doc/html/gobject/gobject-Generic-values.html">native GValue</a> 
  */
 public class GValue extends com.sun.jna.Structure {
 	/*< private >*/

Modified: trunk/src/gobject/runtime/MainLoop.java
==============================================================================
--- trunk/src/gobject/runtime/MainLoop.java	(original)
+++ trunk/src/gobject/runtime/MainLoop.java	Fri Jan 30 05:35:09 2009
@@ -64,7 +64,46 @@
 import com.sun.jna.Pointer;
 
 /**
- * The GLib main loop.
+ * Managed peer for a native { code GMainLoop} structure.  There is typically one
+ * main loop associated with a program, which reacts to events.
+ * <p>
+ * This class includes custom methods and interfaces for event scheduling, making use of
+ * { link java.util.concurrent} classes.  This methods are crucial for bridging between
+ * asynchronous worker threads and the main event (UI) thread.
+ * <p>
+ * Scheduling code to run in the future:
+ * <pre>
+ * MainLoop loop = MainLoop.getDefault();
+ * 
+ * loop.invokeLater(5, TimeUnit.SECONDS, new Runnable() {
+ *     public void run() {
+ *         System.err.println("Hello 5 seconds later");    
+ *     }
+ * });
+ * </pre>
+ * <p>
+ * Creating a worker thread for an expensive task, and then passing the result
+ * to the main thread to update the GUI:
+ * <pre>
+ * MainLoop loop = MainLoop.getDefault();
+ * 
+ * loop.threadInvoke(new Callable<String>() {
+ *     public String call() throws Exception {
+ *         HttpURLConnection conn = (HttpURLConnection) new URL("http://www.example.com";)).openConnection();
+ *         return conn.getContentType();
+ *     },
+ *     new MainLoop.Handler() {
+ *         public void handle(Future<String> result) {
+ *             try {
+ *                 contentTextArea.setText(result.get());
+ *             } catch(Exception e) {
+ *                 showErrorDialog(e);
+ *             }
+ *         }
+ *     });
+ * </pre> 
+ * 
+ * @see <a href="../../gtk-doc/html/glib/glib-The-Main-Event-Loop.html">native GMainLoop</a> 
  */
 public class MainLoop extends RefCountedObject {
     private static MainLoop defaultLoop;
@@ -273,8 +312,8 @@
     }
     
     /**
-     * Stub interface for { code queue}.
-     * @author walters
+     * A callback which is invoked when the result of a threaded invocation
+     * is complete.
      *
      * @param <T> Type of object passed to queue
      */

Added: trunk/src/gobject/runtime/package-info.java
==============================================================================
--- (empty file)
+++ trunk/src/gobject/runtime/package-info.java	Fri Jan 30 05:35:09 2009
@@ -0,0 +1,6 @@
+/**
+ * Provides fundamental classes mapping to core functionality
+ * in <tt>GLib</tt>, <tt>GObject</tt>, and parts of <tt>Gio</tt>.
+ */
+package gobject.runtime;
+
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]