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

Next: + Gnomify the setup, configuration, etc.

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

      + Write up the GTK+HS conventions!

      + How about debauch in addition to the efence option?

      + We should use -#include<gtkMarsh.h> and ../glib, ../gdk, and ../gtk to 
        the path list where the compiler looks for header files (otherwise, it 
        doesn't work correctly when a compile in another than the current
        directory is triggered due to a make dependency)

      + implement some of the often used types and functions from GDK
        (impl event records and use them in the signal handler for events in
        GtkWidgetSignal.hs)

	Check again where we need safe calls.

      + text widget
      + scrolled windows

      + use in configure.in? 
	  Define __HASKELL__=98 and __HASKELL98__ as preprocessor macros for
	  all Haskell 98 compilers.


OBSERVATIONS:
~~~~~~~~~~~~~

It seems like there are some redundant functions or functions, which are used
internally, but dont't seem to make sense to be provided in the Haskell
binding (although, they are in the .h files) -- for example, the *_get and
*_set functions and some of the *_new functions, maybe also the *_init
functions. 

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.

Work:
~~~~~

* Nick Bailey writes, ``Combobox, Menu and CList are my votes for your next
  widgets to add.'' 

* `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).

* Use `ForeignObj' and `MutableByteArray's, but we need casts to `Addr'.

* 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

* Should we abbreviate all the `...Signal' module names to `...Sig' and
  correspondingly the "new",ie, not native GTK+, functions in these modules?

* 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...

* The definition of `GtkConfig.GBool' works only because the compiler doesn't
  implement UniCode.  The FFI should support a type that is guaranteed to be
  mapped to C's char.

* It is inconvenient that there is no *cheap* & *portable* way to return
  multiple values from an external routine; passing pointers to storage areas
  is not cheap, as each allocation needs a FFI call.  Passing a reference to a 
  whole struct would be better, but is more difficult to realize when the
  returned values are not all of the same type.

  This is important for the get-routines and maybe the efficiency of frequent
  gets and sets.


The Big Rewrite
--------------- 

As soon as the beta of the interface generator C->Haskell is ready, there will 
be a substantial rewrite of Gtk+HS.  After the rewrite is completed and some
of the more often used widgets like menus have been added, the binding is
scheduled to go into beta (all of this will hopefully be completed before the
next Millennium).  Items for the Big Rewrite:

* gtkInit :: Maybe (String, [String]) -> IO (String, [String])

  In case of `gtkInit Nothing', the `gtkInit' calls `getProg' and `getArgs' to 
  obtain the arguments.

* All `g', `gdk', and `gtk' prefixes are dropped in favour of using Haskell's
  ability for qualified imports to disambiguate name spaces.

* All enumerations and `foreign import' declarations will be automatically
  generated by C->Haskell.  Furthermore, the new marshaling routines are used.

An Elisp function that converts `gtkXXX' into `Gtk.xXX' and `GtkXXX' in
`Gtk.XXX' (same for GDK) or when C-u given produces `xXX' and `XXX',
respectively, would probably come in handy.

Long term
---------

* Check out EasyGTK

    http://users.linuxbox.com/~drow/EasyGTK/

  Something similar might even get much more elegant in Haskell.

* Check interaction with the `Concurrent' module.

* The current modules try to stay as close to the C routines as possible while
  taking the requirements of Haskell like strong typing in account.  It
  would also be interesting to put a layer on to of these that smoothes out
  some of the awkward points in GTK+ and makes use of Haskell data structures
  and abstraction facilities (e.g., build boxes from lists of widgets with one 
  function call etc)


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). 
