java-gnome-hackers

[java-gnome-hackers] Problem with TextIter / Generator

[Stefan P. <st...@pr...>]

Hi all!

First of all: Andrew "tricked" me into having a closer look at the
sources and do needed coverage of GTK methods myself, so I just found
myself digging through the sources. I hope I can help you add some
coverage in the future.

I started working on coverage for TextBuffer/TreeView and friends and
nearly immediately stumbled into my first problem, for which I request
your advice.

I want to write a method
  TextIter TextBuffer.getStartIter()

Having a look at GtkTextBuffer I found
  static final void getStartIter(TextBuffer self, TextIter iter) {
    ..
    gtk_text_buffer_get_start_iter(pointerOf(self), pointerOf(iter));
    ..
  }

So, I need an instance of a TextIter to call that method - but where do
I get that from? Normally I would expect a native method like 
  gtk_text_iter_new
but it seems that it does not exist.

The GTK API docs claim that "... GtkTextIter is a struct designed to be
allocated on the stack; ...", so normally I would call it like
  GtkTextIter start_iter;
  GtkTextBuffer foo = ...;
  gtk_text_buffer_get_start_iter (&foo, &start_iter);

This is basically what is in GtkTextBuffer.c 
Java_org_gnome_gtk_GtkTextBuffer_gtk_1text_1buffer_1get_1start_1iter
except that that method requires a pointer to a GtkTextIter, although it 
should be the method to create one.

Manually patching GtkTextBuffer.c is out of the question, since it is 
generated, so now I am stuck.

Can anyone shed some light on this. Did I miss something? Any idea how to 
solve this?

Cheers,
  Stefan
  Germany, Bremen

Re: [java-gnome-hackers] Problem with TextIter / Generator

[Andrew C. <an...@op...>]

On Sat, 2008-05-03 at 23:07 +0200, Stefan Prelle wrote:
> I started working on coverage for TextBuffer/TreeView and friends 

Hey cool. I've just been beginning work on bits of that myself. [note 1,
note 3]

> So, I need an instance of a TextIter [but no way to instantiate one]
> 
Yup. This is a situation we've come across a few times already.

Having worked out coverage of TreeView, it provides a road map for
other complicated APIs. For instance, almost all the bindings layer
methods dealing with TreeIters are nasty this way, the canonical example
being TreeModel's getIterFirst().

++

The general problem class is that things like GValue, GtkTreeIter,
GtkTextIter, GdkFont, etc are not proper objects (and are not even
GBoxeds in some cases) but are merely C APIs sugar. Two aspects to
this:

1) C binding leakage as library API
-----------------------------------

In C, one simply stack allocates such a struct and then passes it in by
reference. Too easy.

Language bindings can't do that, so something that should only exist for
a few milliseconds at most ends up persisting long after until garbage
collection runs. That's just the way it is, but it's annoying (and
something I spent considerable effort in Berlin trying to point out to
GTK hackers that such things, while nice C bindings, are hideous for
language bindings and should not be used in public GNOME library APIs).

The upshot of this is that there is no _new() function in the .defs data
because there aren't _new() constructors for such things in GTK.


2) No code generation of allocators for structs et al
-----------------------------------------------------

We don't yet [note 2] have anything in the code generator as yet to
generate allocators for Boxeds (and structs masquerading as Boxeds). So
you have to write one yourself.

> Manually patching GtkTextBuffer.c is out of the question, since it is 
> generated

That's correct.

But we do have a route around that, of course, necessary for cases where
the generated code doesn't do what we need. They are colloquially known
as Overrides. I am a bit surprised you didn't notice any. Oh well.

> , so now I am stuck.

TreeIter needed a hand-written instantiation function because of (2)
above. See: src/bindings/org/gnome/gtk/GtkTreeIterOverride.{java,c} as
called by TreeIter's <init>().

So if writing TextIter, it will be much the same. Be sure to follow the
architecture conventions at each layer.

AfC
Sydney



Notes,

[1]: The last java-gnome 2.x application we have that remains unported
to 4.0 is something that makes heavy use of TextViews. I remember very
vividly how difficult I found it circa 2004 working with the
TextView/TextBuffer/TextTag family of APIs.

Unlike the equally obscure TreeView/TreeModel APIs (where we were able
to make significant improvements) I'm not too sure yet if there is much
scope for rescuing TextBuffer. That said, across much of java-gnome,
fairly impressive improvement has come from simply having to the Java
bindings become faithful to the underling libraries and be
algorithmically mapped (modulo adding type safety, _not_ exposing
unnecessary crap, and other java-gnome -isms) and already just doing
that seems to have been an improvement.

Anyway, the patterns we developed in TreeView will no doubt serve as a
road map for TextView. I've already found this with TextTag and it
sharing quite a bit in nature with CellRenderer, being GObject property
driven.

[2]: this is only the third or fourth time we've need to write such an
override, and they've been a bit different each time; for Boxeds we
could use the supplied _copy() and _free() functions (and do in the hand
crafted override code), but for plain structs it's all hideously manual.
Lot of extra generator code for such a few number of cases, although it
would be nice to see at some point. Again,
read src/bindings/org/gnome/gtk/GtkTreeIterOverride.c

[3]: I spent a lot of time over the last few days beating TextTag into
submission. The internal GObject property binding mechanism needed a
fair bit of further coverage and fixing, and I added a fairly
significant amount of safety checking as well.

I also did some basic work on a few Pango classes where they are used as
constants in GTK text manipulation. This was nasty: I needed to
introduce something to enable strong type safety for constants that were
double, rather than int, based.

[This is not work on
Pango-as-text-drawing-library-to-be-used-with-Cairo; (Vreixo is
interested in that area) but I did implement the constants that came up
as being necessary in the TextTag properties I wrote setters for].

++

So definitely feel free to merge from my 'textview' branch at
bzr://research.operationaldynamics.com/bzr/java-gnome/hackers/andrew/textview/ 

... but be aware it's very much work-in-progress, no where near
'mainline' ready, and not really something I can afford to be spending
much time on. Nevertheless there is a lot of infrastructure fixing
that's gone on there already, and more that will become necessary. More
to the point it's always good to collaborate with someone working on an
area rather than having their work being duplicate effort.

-- 
Andrew Frederick Cowie

Operational Dynamics is an operations and engineering consultancy
focusing on IT strategy, organizational architecture, systems
review, and effective procedures for change management. We actively
carry out research and development in these areas on behalf of our
clients, and enable successful use of open source in their mission
critical enterprises, worldwide.

http://www.operationaldynamics.com/

Sydney   New York   Toronto   London

Re: [java-gnome-hackers] Problem with TextIter / Generator

[Stefan P. <st...@pr...>]

Am Sonntag, den 04.05.2008, 16:23 +1000 schrieb Andrew Cowie:
> > So, I need an instance of a TextIter [but no way to instantiate one]
> > 
> Yup. This is a situation we've come across a few times already.

Ok, glad to know I didn't miss anything.

> But we do have a route around that, of course, necessary for cases where
> the generated code doesn't do what we need. They are colloquially known
> as Overrides. I am a bit surprised you didn't notice any. Oh well.

The thought to look at TreeIter (or other iterators) did not cross my
mind. :) Shame on me.

> So definitely feel free to merge from my 'textview' branch at
> bzr://research.operationaldynamics.com/bzr/java-gnome/hackers/andrew/textview/ 
> 
> ... but be aware it's very much work-in-progress, no where near
> 'mainline' ready, and not really something I can afford to be spending
> much time on. Nevertheless there is a lot of infrastructure fixing
> that's gone on there already, and more that will become necessary. More
> to the point it's always good to collaborate with someone working on an
> area rather than having their work being duplicate effort.

I did some work on the 'textview' branch and I have it working now. You
will get it per email in a few minutes.
Having at least minimal (without tags) TextView coverage in java-gnome
is something that should be included in the mainline with the next
release. You cannot build GUIs with simple multiline textfields without
it, which I consider an important feature.
So, I think I'll help you on that branch - although I have no experience
with tagged TextBuffers yet. But that can be changed in the process.

Cheers,
  Stefan