home *** CD-ROM | disk | FTP | other *** search
/ Dream 57 / Amiga_Dream_57.iso / Linux / Libs / pygtk-0_5_3.README < prev    next >
Text File  |  1998-11-04  |  9KB  |  220 lines
  1. Gtkmodule and Gtkinter
  2. ======================
  3. Author: James Henstridge <james@daa.com.au>
  4.  
  5.  
  6. This archive contains modules that allow you to use gtk in Python
  7. programs.  At present, it is a fairly complete set of bindings.
  8. Despite the low version number, this peice of software is quite
  9. useful, and is usable to write moderately complex programs.  (see the
  10. examples directory for some examples of the simpler programs you could
  11. write).
  12.  
  13. If you have any enhancements or bug reports, please send them to me at
  14. james@daa.com.au.  If you are going to send me diffs, my prefered
  15. format is unified diff (ie. diff -u), although context diffs are OK as
  16. well.  Please don't send me diffs which don't have any context, as
  17. these are almost useless if I try to apply them manually, or have a
  18. different version of the source tree.
  19.  
  20.  
  21. New Versions
  22. ============
  23.  
  24. New versions of this package can be found at
  25.   ftp://ftp.daa.com.au/pub/james/python/
  26.   ftp://ftp.gtk.org/pub/gtk/python/
  27.   ftp://ftp.python.org/pub/contrib/Graphics/
  28.  
  29.  
  30. Mailing list
  31. ============
  32.  
  33. There is a mailing list for pygtk.  You can subscribe to it by sending mail
  34. to pygtk-request@daa.com.au with the word subscribe in the body.  The list
  35. address is pygtk@daa.com.au.
  36.  
  37.  
  38. Copyright Information
  39. =====================
  40.  
  41. This software is covered by the GNU Library General Public Licence
  42. (version 2, or if you choose, a later version).  Basically just don't
  43. say you wrote bits you didn't.
  44.  
  45.  
  46. Compilation
  47. ===========
  48.  
  49. This archive contains a single C module called gtkmodule.  It contains
  50. an almost direct mapping of the functions in GTK including GTK signal
  51. handling, and the gtk_object_new/gtk_object_set commands.  This
  52. version REQUIRES gtk+-1.1.2 or later, as it includes support for
  53. features not found in previous versions, and there are
  54. incompatibilities between versions.  Also if you want the GdkImlib
  55. extension, you must have Imlib version 1.3 or greater.  I recommend
  56. getting the latest stable versions of these libraries before compiling
  57. pygtk, as it will make your system more stable.
  58.  
  59. This module is generated by SWIG version 1.1p2 or newer (older
  60. versions may work -- I just haven't tried them).  A copy of the
  61. generated gtkmodule.c is included in the base directory of the
  62. distribution.  If you wish to regenerate this file, you should get
  63. into the swigsrc directory in the distribution, and look at the
  64. makefile for tips on how to generate gtkmodule.c.  The SWIG interface
  65. files have some comments in them.
  66.  
  67. To compile gtkmodule, first run "./configure" from the base directory
  68. of the distribution.  It requires that you have python in the path,
  69. and python has been installed properly.  If python is not in the path,
  70. you could try running "./configure --with-python=/subdir/python".  This
  71. should generate Makefile from the files Makefile.pre.in and Setup.in.
  72.  
  73. Now you should be able to run "make" to compile the module.  Now you
  74. should install the files.  I have provided an install target to the
  75. makefile, so you should be able to just type "make install".  On
  76. systems with Python 1.5 and later, it installs to the site-packages
  77. directory (using prefix and exec_prefix where appropriate).  For
  78. Python 1.4, it installs the python code to $(prefix)/lib/python$(version),
  79. and the libraries to $(excec_prefix)/lib/python$(version)/sharedmodules.
  80. It also compiles .pyc files from the python code.
  81.  
  82. If you had a copy of gdk_imlib installed on your system (and configure
  83. could find it) when you built pygtk, a wrapper for it will have been
  84. installed with the main pygtk modules.  A simple example of using the
  85. GdkImlib module is in the directory examples/imlib.
  86.  
  87. If you have trouble with building or installing any of the code, please
  88. tell me -- it is the only way I can fix the problem.  If you do mail me,
  89. please put something sensible in the subject line so I can tell what it
  90. is about.
  91.  
  92.  
  93. Upgrading
  94. =========
  95.  
  96. Note that from version 0.5.0 up, pygtk uses GTK v1.1.  Since there
  97. were some changes to the API, pygtk has changed accordingly.  The main
  98. one that will cause problems is the GtkAcceleratorTable.  In this
  99. version, it has been removed and replaced with the GtkAccelGroup.
  100. Also note that some of the functions that refer to that type may have
  101. changed slightly.  The rest of the changes are mostly invisible, since
  102. they are mainly internal, and not touched upon by most people's code.
  103.  
  104. Also, I have changed the arguments for the Gtkinter.new function.  Now
  105. instead of object arguments being passed in as a dictionary, they are
  106. passed in as keyword arguments.  This is possible because the 'Gtk*::'
  107. prefix is no longer needed.
  108.  
  109. The last change will only affect people who don't use the Gtkinter.py
  110. wrapper.  I have changed the name of the low level gtk module.  You
  111. will need to change:
  112.   from gtk import *
  113.   gtk_init()
  114. to:
  115.   from _gtkbase import *
  116.   from _gtk import *
  117.   gtk_init()
  118.   pygtk_init()
  119.  
  120.  
  121. Tests
  122. =====
  123.  
  124. After having compiled and installed gtkmodule, GTK and Gtkinter, you
  125. may want to test them.  In the examples directory there are a number
  126. of programs you may want to use to test gtkmodule and Gtkinter.  These
  127. programs rely on being able to find gtkmodule, GTK and Gtkinter, so
  128. you must have installed them somewhere on your python path.  (Typing
  129. "PYTHONPATH=../.. python filename.py" from the examples directory is
  130. enough, after building gtkmodule)
  131.  
  132.  
  133. _gtkmodule and GTK.py
  134. ====================
  135.  
  136. This module contains an almost complete translation of the functions
  137. in the gtk library.  To start up, put in the command "from gtk import
  138. *".  If you want to use any of the constants, type "from GTK import
  139. *".  The constants all have the "GTK_" removed from the start.  Before
  140. creating any GtkObjects, you should execute the command "gtk_init()".
  141. Unlike the C equivalent, you don't have to specify an argument list,
  142. since there are other ways to get at it.
  143.  
  144. When you are using the functions in this module, you will find that
  145. there is no need to use any of the type casting macros on GtkObjects,
  146. since they are all stored inside the same python type.  Each function
  147. in the module does its own type casting.
  148.  
  149. In this module there are only two signal connection functions --
  150. gtk_signal_connect and gtk_signal_connect_after.  The other functions
  151. can be emulated with the use of callable class instances wrapped
  152. around the signal handler.  Also signal handlers are not parsed the
  153. extra data argument.  The reason for this is because the code has to
  154. keep track of both the python signal handler and its C wrapper.
  155.  
  156. In the gtk_object_new and gtk_object_set functions, the property
  157. setting argumetns have been compressed into a single dictionary as an
  158. argument.  This dictionary has string keys that correspond to the
  159. property names, and the values are the property values.  The reason
  160. that I did not use keyword arguments is that things like
  161. "GtkWindow::title" are not valid keywords, so unfortunately we have to
  162. use this clumsy syntax.
  163.  
  164.  
  165. Gtkinter.py
  166. ===========
  167.  
  168. This module is a wrapper for gtkmodule.  You start using it by
  169. executing the command "from Gtkinter import *".  This will give you
  170. access to all of Gtkinter, and also import GTK, the constants module,
  171. for you.
  172.  
  173. This module implements an object oriented wrapper for gtk.  Probably
  174. the best way to get a feel for it, is to read some of the source
  175. code.  Basically, there is a class for each GtkObject type.  Each
  176. class implements the functions specific to that GtkObject type as
  177. methods.  (ie. GtkWidget.show() is equivalent to gtk_widget_show()).
  178.  
  179. The classes are set up such that their inheritance tree matches that
  180. of the actual GtkObjects.  This means that you can call
  181. GtkWidget.show() from a GtkWindow class instance.
  182.  
  183. The constructors for each of these classes corresponds to the
  184. gtk_*_new functions.  Through the use of default arguments, both the
  185. gtk_*_new and gtk_*_new_* functions are both supported through the
  186. constructor.
  187.  
  188. There are also a few extra functions in Gtkinter.  These are new(),
  189. mainloop() and mainquit().  The function new() implements
  190. gtk_object_new.  It's first argument can be either a string, or one of
  191. the classes in the module.  The second argument is a dictionary that
  192. is almost passed to gtk_object_new after converting Gtkinter Objects
  193. to GtkObjects.
  194.  
  195. The function mainloop() is basically just the function gtk_main(), and
  196. the function mainquit is equivalent to gtk_main_quit().
  197.  
  198. For further information on the interface, please see the source file
  199. Gtkinter.py.
  200.  
  201.  
  202. Should I Use Gtkmodule or GtkInter?
  203. ===================================
  204.  
  205. You should probably use the striaght gtkmodule, if you are using
  206. python to prototype a C application that will use GTK, but in most
  207. other cases, Gtkinter will probably be a lot easier to use, and will
  208. look more natural in a python program.
  209.  
  210.  
  211. Contacting the Author
  212. =====================
  213.  
  214. You can contact me at the email address <james@daa.com.au>.  I try to
  215. answer my email quickly, but occasionally there will be a bit of a
  216. delay.  If you have an idea for a way to extend GTK, have found a
  217. problem with the code (I don't think there are many bugs anymore), or
  218. would like to contribute some code, please feel free to contact me.
  219.  
  220.