								     -*-text-*-
		 TODO for the GTK+ Binding for Haskell
		 =====================================

Next: + add conditionals to c2hs and use this to support both GTK+ 1.2 and
	GTK+ 2.0

      + configure: the notices about the options introduced by GTK+ is
        unclear, because some of these options are later removed; maybe have a
        warning where the options are removed, which prints which options are
        dropped

      + Peter Strand writes ``I also get a "Duplicate instance declarations"
        error since both GtkFileSel and GtkMenuItem contains a Storable
        instance for Widget.  Moving it to GtkWidget.chs works but there is
        perhaps a better way?'' 

      + Keith Wansbrough provided preliminary support for libglade in
        gtk-config, but libglade must still be compiled in the right package.

      + integrate and install IDoc generated interface documentation

      + we really want to derive Eq for all widgets

      + Have package specs for ext/ packages

      + Write up the GTK+HS conventions!

      + Due to a shortcoming in c2hs, `GdkVisual.visualGetType' can currently
	not be bound.

      + use a stamp file to do make depend automagically if necessary; and
        maybe also for configure - like the automake stuff

      + Get rid of the -#include by using custom header files; do this with
        moving to the new FFI, as it isn't much of an issue with package
        support

      + rewrite GtKGLArea's `viewlw.c' into Haskell

      + correct foreign export dynamic definitions in GtkCListSignal.hs and
        drop support for the buggy 4.08.x series

      + would like to support Haddock, too



Missing GTK+ 1.2 widgets
~~~~~~~~~~~~~~~~~~~~~~~~
- GtkAccelLabel (usually not explicitly needed by application code)
- GtkArrow[small]
- GtkAspectFrame[small]
- GtkCalendar
- GtkColorSelection[small]
- GtkColorSelectionDialog[small]
- GtkCurve
- GtkDialog[small]
- GtkFixed[small]
- GtkFontSelection
- GtkFontSelectionDialog
- GtkGammaCurve[small]
- GtkHRuler[small]
- GtkImage[small]
- GtkInputDialog[small]
- GtkInvisible (usually not explicitly needed by application code)
- GtkItemfactory[big]
- GtkLayout
- GtkPacker
- GtkPlug
- GtkPreview
- GtkRadioMenuItem (started)
- GtkSocket
- GtkSpinButton[big] (started)
- GtkTearoffMenuItem[small]
- GtkTipsQuery
- GtkToolbar[big]


For GTK+ 2.0
~~~~~~~~~~~~

* gdk/Makefile: GdkXXX.chs-HEADER definitions have to be adapted


Work:
~~~~~

* Widgets at the tip of the object tree like GtkList should probably not have
  a class and we shouldn't use ``GtkListClass lst -> lst''-style arguments for
  them - this makes everything more verbose and doesn't really help anything.
  But it is difficult to say for which widgets this applies.

* How about debauch in addition to the efence option?

* `GLib.gThreadInit' should maybe verify that the installed version GLib has
  thread support enabled (there is a variable/macro? to test this).  Or, how
  about a ./configure option --enable-threads.  It checks that multi-threading 
  is supported by GLib/GDK and by the Haskell system.  If threads are not
  enabled, either `GLib.gThreadInit' should terminate the program, or all the
  thread routines are defined to do nothing (this could be achieved, by having 
  a `Config.hs.in' file mangled by .configure).

* Callback closures still have to be freed in case of a "delete" signal.
  `gtkSignalDisconnect' already takes care of unregistering the callback
  closure, but when the widget is deleted, nothing happens automatically at
  the moment.  There should probably be an automatic mechanism in the library
  that registers a cleanup delete signal handler whenever any signal is
  registered (be careful about the cyclic dependency arising for delete
  signals themselved).

  The easiest solution is probably to use gtk_connect_signal_full.  It allows
  a destroy function that is invoked on the user data.  When we pass the
  callback as both function pointer and user data, we can use freeHaskellPtr
  as the destroy function.

* Use `ForeignObj'

* Which calls can be made unsafe.

  ATTENTION: Any call that can trigger a signal must be made safe!!  This is
	     currently not the case because of the _call_GC_ bug.  See also
	     examples/EntryTest.hs

* Routines like `GtkWindow.gtkWindowNew' may fail and this has to be handled
  gracefully... 

  Also see Michael Hobbs e-mail.

* GTK+ may allow us to always free external addresses when we convert them 
  to Haskell objects (as it usually gives us our own copies of things)

  How about deallocing the objects that we get from GTK+?  Somehow the
  programmer has to explicitly do that...


Long term
---------

interactive Haskell - a layer for convenient GTK+ programming in Haskell.


DOCU (should eventually be placed in a file of its own)
~~~~

* We don't support programming of new widgets and the like in Haskell.

* guint is mapped to Int in Haskell (there is no nice support for unsigneds in 
  Haskell) -- this shouldn't be a problem as in GTK+ guint is usually used as
  an indication that a value cannot be negative, not because the increased
  range of positive values really matters

  The Haskell bindings checks that no negative values are passed to guint
  arguments. 

* Signals: We provide only the functions operating on `GtkSignal' and the
  lookup functions from signal names.

  The `func_data' for the signal handlers doesn't appear explicit, as we
  anyway use complete closures as handlers.

  Without multi-parameter classes, there is no way to have an overloaded
  `gtkConnectSignal' function, but we need to use explicit instances
  `gtkConnectSignalButton' etc (a generic function would have to ensure that
  the object and the handler are compatible, which requires a binary relation
  between types).

* The `fromGtk...' methods may seem strange, but they are definitely required
  to implement overloaded signal handlers (and they are supported by the
  underlying GTK+ object system)

* We provide an explicit type for `gint' and `gboolean' in `GtkConfig', but
  none for the `gint16' etc types, because their representation is fixed
  anyway.

* Some functionality of GTK+ is not available as function calls, but as C
  macros or direct access to the structures; therefore, we need some
  auxilliary C modules to provide a function-based interface for these things.

* Enum rationale. Data types instead of functions calling C routines that
  return the macro value because:

  - It is inefficient (the compiler cannot inline the
    constants as they are FFI calls and FFI calls - even
    unsafe ones - are more expensive than purely functional
    calls).

  - I think it is nicer to use data constructors (ie, upper
    case identifiers) for enums.

  - Even with data constructors, I can always change the
    implementation to use a C call (by redefining the `toEnum' 
    function in the enumeration type's `Enum' class
    instance).

  - It wouldn't be difficult to write a program checking the
    correctness of the Haskell data definitions against GTK+'s 
    header files (we could even think about a simple
    pre-processor that generates the definitions from the .h
    file). 

* Furthermore, some functions, which are defined for the convenience of the
  C programmer (for example, to replace two function calls by one) don't make
  much sense in Haskell, because they are extremely easy to compose from their
  components in Haskell's expression syntax.


Release Checklist
~~~~~~~~~~~~~~~~~

(1) In root of working directory,

      % make tar

(2) Compile the resulting source distribution with latest ghc stable release:

      % tar xzf gtk+hs-x.y.z.tar.gz
      % cd gtk+hs-x.y.z
      % ./configure [--enable-ih --with-hopengl=HOPENGL --enable-gtkglarea]
      % make

(3) Regression testing:

    * Execute the tests in `examples/', `ext/gtkglarea/examples/', and
      `ih/examples/'

(4) Check that is up-to-date NEWS

(5) Register CVS tags (syntax: GTKHS_x_y_z)

(6) Make newest `tar' and build rpm

(6) Put tar.gz and rpm sources and binaries up on Web page

(7) Announce: haskell@haskell.org, freshmeat.net
