RE: [java-gnome-hackers] My work so far

[Jeffrey M. <Jef...@Br...>]

> I will also work on example apps using these widgets. Is 
> there any plan
> of what example apps should be produced? Do we just follow 
> the previous
> versions, or write whatever would be useful. IMHO, it would be a good
> idea to create a java clone of the c gtk-demo program. I believe this
> demonstrates all of the gtk widgets with a useful interface which also
> displays a description and source for each. If this is done, the many
> smaller example apps may not be required (of course, there 
> would have to
> be some for gnome, etc.)

I think it would be a good idea to present this example.  I
do not thing we should consider this as a replacement for the
small examples.  gtk-demo (like test-gtk before it) is a large
example and for a beginner it could be overwhelming.  I think
small examples that demonstrate one widget or a set of related
widgets are very useful for somebody trying to learn the API.

> Issues 
> ------
> ** Button Constructors:
> There are four possible constructors for button:
> - no arguments
> - a label
> - a label containing Mnemonic characters (keyboard accelerators)
> - a stock item ID (string)
> I have been having trouble deciding how to best implement this.
> Currently, my best idea has been to have
> Button()
> Button(String caption)
> Button(String caption, boolean hasMnemonic)
> Stockbutton(String stockID)
> This would require creating a StockButton Class, which is the same as
> the Button class except that it uses a different constructor. 
> The other methods in button allow the 'type' of button to be changed,
> e.g. make a stock button into a normal button.
>
> Are there any other ideas for this? or should I implement the above
> suggestion

Another possibility might be to enhance the StockName object
that exists in the gtk package.  It already contains a static
member for each of the #defines in gtkstock.h.  You could add
a constructor that will take a parameter that is one if its' 
static members and assign it to a value.  Then you could create 
a constructor for the Button widget that takes a StockName object.
We could also reuse the StockName object for all methods that
take a string that represents a stock id.

> ** Naming convention
> I have been trying to make the names more consistent (e.g. 
> using column
> all the time instead of a mixture of column and col)
> The Gtk Button has two very strangly named methods - get/set
> UseUnderline. From the gtk reference, it seems that these 
> should really
> be called get/set useMnemonic. I will change these unless 
> there are any
> objections. 

There is no need for the public interface to emulate the native
methods.  Our goal is to make a higher-level OO class library 
that should be easier to use than the native C libraries.  Feel
free to define method names and parameter lists that simplify
access to the native peers.  Also, there are many methods in the
native libs that were not intended for public use.  Often you will
find this documented in the docs.  We should not provide access
to these methods.  Finally, there are many methods that are either
redundant or are so obscure that they will probably never be used
if we make them available.  Feel free to excluded these types of
methods as well.  Use your judgment to make a public interface that
is clear, concise, and easy to use.

> 
> ** get_type 
> These native methods seem to be present in most classes. What 
> are their
> purpose?

The get_type methods and the GType object are the glib method for 
runtime identification of objects and types.  Java already provides
this ability and I am not completely sure we need to implement 
these methods at this time.  Hopefully this will become clearer as
we move forward.  For the time being there is no need to implement
a method to access type information.

> ** Enum 
> for many of the enums, e.g.ReliefStyle, the methods and, or, xor, etc.
> don't seem to have any use. Also, the test method would, 
> IMHO, be better
> named equals.

Enums are frequently bitwise combined in the native libs.  For example,
the AttachOptions parameters for the attach method of Table can provide
several options.  It is quit common to combine both the EXPAND and
FILL options.  For this you need the 'or' method.

The equals method doesn't work simply because you can combine several
of the enum values.  If the AttachOptions enum has both EXPAND and FILL
and you call equals on FILL what should it return?

> ** Box 
> I am confused about how the query child packing should work
> native static final protected void 
> gtk_box_query_child_packing (int box,
> int child, boolean[] 
>         expand, boolean[] fill, int [] padding, int [] packType);
> native static final protected void gtk_box_set_child_packing (int box,
> int child, boolean 
>         expand, boolean fill, int padding, int packType);
> Could someone with more experience of gtk please tell me why the
> parameters are all arrays? (what do they return?)

In java it is not possible to pass primitives as references.  If
there is a native method gtk_widget_get_pointer(int *x, int *y)
there is no way to wrap this passing ints. Arrays are always passed
by reference.  The correct way to wrap the get_pointer method is to do
the following:

static protected gtk_widget_get_pointer(int handle, int [] width, int []
height);

public Point getPointer() {
  int [] x = new int[1];
  int [] y = new int[1];
  gtk_widget_get_pointer(handle, x, y);
  return new Point(x[0], y[0]);
}

I would not provide a public interface to the gtk_box_query_child_packing
method.  The purpose of this method is to return the packing values that
were used when a widget was added to the box.  I have worked with java for 
5 years and have never had to query a layout manager to determine how a 
widget was packed after the fact.

> **Documentation 
> How much javadoc documentation should we provide? As an 
> example, in the
> Label widget, I copied most of the gtk documentation to the 
> source file.
> This may seem a little excessive; however if the user is expected to
> look only at the java-gnome api docs, they may want such a level of
> detail. 

There is no such thing as too much documentation.  There is only too
little documentation.  What we are build is intended for other developers
to use.  It is only useful if developers can understand how to use it.


-Jeff