lib/gtkNode/README

   1   the project has moved to Google.
   2
   3 http://code.google.com/p/gtknode/
   4
   5
   6   Yet Another GUI framework for Erlang - gtkNode
   7
   8   DESIGN GOALS
   9
  10 * GUI separated from application by message passing
  11 * distributed (application and GUI can run on different machines)
  12 * centered around a GUI builder
  13 * small volume of (hand-written) code
  14 * pre-documented
  15
  16   ARCHITECTURE
  17
  18   a c-node (a daemon that implements the Erlang distribution protocol)
  19 that instantiates the GUI from a configuration file. the c-node sends
  20 messages to the Erlang node when the user interacts with the GUI; the
  21 Erlang application changes the state of the GUI by sending messages to
  22 widgets in the c-node. the widgets should look like Erlang processes
  23 with registered names. the protocol should look something like this.
  24
  25 CnodePid ! {aWidget,dosomething,Args}       % erlang->cNode
  26 ApplicationPid ! {reply, Val}               % cNode->Erlang
  27 ApplicationPid ! {signal,aWidget,eventType} % cNode->erlang
  28
  29   in this example aWidget is the name given to a widget in the
  30 configration file. it can also be thought of as the registered name of
  31 the process implementing the widget in the c-node.
  32   the c-node is responsible for garbage-collecting all temporary data.
  33
  34   IMPLEMENTATION
  35
  36   i chose GTK2 (www.gtk.org) as the framework. there were several reasons;
  37
  38 * it has an eminent GUI builder, Glade (glade.gnome.org)
  39 * it has facilities for instantiating the GUI from the Glade (XML) files
  40 * it has good documentation
  41 * it supports run-time type checking
  42 * its object orientation maps well to Erlang (Obj.meth(Arg) -> Obj!{meth,[Arg]})
  43 * the Python binding provides useful tools for code generation
  44 * seems to be the Future (tm) in the *nix world, and runs on Windows too.
  45
  46   there's three parts to the gtkNode. a main loop, some support
  47 functions for object storage and marshalling, and a whole bunch of
  48 generated wrapper functions.
  49   The main loop is a pretty generic c-node that simple-mindedly
  50 receives lists of 2-tuples;
  51
  52 {atom('Func'), list(boolean()|integer()|float()|atom()|string())}
  53
  54   it checks that there exists a function Func and calls it, passing a
  55 pointer to the argument list. the Func's are wrapper functions
  56 generated from the GTK header files, and unmarshalls and type checks
  57 the arguments before the actual GTK functions are called.
  58   the return value of the GTK function is sent back to the Erlang node.
  59
  60   a different kind of message is sent if there is an interesting event
  61 in the GUI (e.g. a button is pressed), where "interesting" means specified
  62 in the Glade file.
  63
  64   REFERENCE
  65
  66   the c-node is started thus;
  67 gtkNode node host regname cookie cnode-name
  68
  69   when started, gtkNode will connect to it's application by sending a
  70 handshake message to {node@host, regname}.
  71   the messsage looks like this;
  72 {{GtkPid,handshake}, []}
  73
  74   the Erlang application sends messages to the gtkNode using
  75 GtkPid. messages look like this;
  76
  77 list({'Gtk_function', [Args]})
  78
  79   E.g., if we have a GtkButton widget, named b1, and we want to use
  80 these functions;
  81
  82 const gchar* gtk_button_get_label (GtkButton *button);
  83 void         gtk_button_set_label (GtkButton *button, const gchar *label);
  84
  85   we could send this;
  86
  87 GtkPid ! [{'Gtk_button_set_label',[b1,"foo"]},{'Gtk_button_get_label',[b1]}].
  88
  89   and we would receive this;
  90
  91 {{GtkPid,reply}, [{ok,void},{ok,"foo"}]}
  92
  93   signals are sent from gtkNode if the signal handler for a specified
  94 signal-widget combination is set to gn_sighandler. the signals look
  95 like this;
  96
  97 {{GtkPid, signal}, {atom(WidgetName),atom(SignalName)}}
  98
  99   E.g., if we delete the GtkWindow named window1 we'll get this signal
 100
 101 {{GtkPid, signal},{window1,'GDK_DELETE'}}
 102
 103   given that we've requested it, of course.
 104
 105   EXAMPLES
 106
 107   the file src/gtkNode.erl implements a controller/middleman for the
 108 gtkNode, it's quite instructive. it is recommended to use this instead of working directly against the c-node.
 109   the file examples/simple/simple.erl implements the Erlang side of a
 110 GUI for a simple 'top' application. the GUI is specified in
 111 examples/simple/simple.glade
 112
 113   GETTING IT
 114
 115 jungerl/lib/gtkNode
 116
 117   see www.trapexit.org or sourceforge.net
 118
 119   BUILDING
 120
 121   i can't see why the should be any real problems to get this to work
 122 on Windows (if it can be said that anything works on Windows); alas, i
 123 have no real wish to try it myself...
 124   look here for more info;
 125 www.gimp.org/~tml/gimp/win32
 126 www.mingw.org
 127
 128   i myself run on solaris 8 and linux (debian).
 129
 130 cd jungerl/lib/gtkNode ; make
 131
 132   should work, if;
 133
 134 * OTP_ROOT is sane
 135 * there is a sane GTK environment
 136
 137   if this;
 138
 139 pkg-config --cflags libglade-2.0
 140
 141  works, i.e. returns a bunch of c-flags, you should be OK.
 142
 143   STATUS
 144
 145   early beta. no major interface changes in the works, but (probably)
 146 lots of bugs.