Users guide for fd2python

Introduction

The simplest way to use fd2python is from the command line option to fdesign.

fdesign -python app

Where app is the name of your application forms design file: app.fd. Several files will be created and as I explain, below, how to add your own routines, I will mention each one and explain their importance in greater detail. But, basically, the file app.fd is converted via fd2python --callback app and it creates 3 files:

app.i
app_cb.py
app_cb.c

Any callback routines you define via the fdesign program will automatically be inserted into the swig file (app.i), the python callback file (app_cb.py) and the C callback file (app_cb.c). If you define callback functions outside the scope of fdesign, then you must follow the procedure described in 'ADDING NEW CALLBACK ROUTINES'.

Running fd2python, either from command line or via 'fdesign -python', multiple times does not overwrite your existing files. You will not lose your changes to 'app.i', 'app_cb.py', and 'app_cb.c'. Anything new will be placed in file 'app.i.new', 'app_cb.py.new' and 'app_cb.c.new'.

You should cut and paste only the new sections of the *.new files into app.i, app_cb.py and app_cb.c appropriately. Or better yet, edit completely new files: app_x.i, app_x_cb.py, and app_x_cb.c, where x is just an arbitrary string. You must modify the makefile appropriately to build the new application, but, you only need to place dependancies for these new files. In app_x.i you must have a %include app.i statement.

BUILDING OR COMPILING THE APPLICATION

Initially, you will not have a make file. To generate a make file for you application, simply run fd2python -makefile app. That will create a file called app.makefile. You simply copy it into Makefile and run make:

mv app.makefile Makefile make

The make file contains all the rules to properly build your application. It will run swig, if you change app.i, it will compile app_cb.c, if you add any C routines, or C wrappers to your callback functions. But, as a rule of thumb, you won't need to run make, if all you do is add python or modify python code.

ADDING NEW CALLBACK ROUTINES

You must edit app_cb.py and add the python code to perform the function The name of the rouines are in lower case (only by convension).

You must edit app_cb.c and add a wrapper for the python routine. All you need to do is construct a routine similiar to the other call back routines. I recommend that you uppercase the entire C routine name. And, I recommend that the python routine be lowercase. While this is only recommended, what really must happen is that the two routines have different names.

You must edit app.i and add prototype definitions in two sections:

You must define the C routine prototype in the '%{' through '%}' section. And, you must declare the C routine toward the end, in the SWIG section.

If you are defining a callback function, you must declare the protoype in the SWIG section with the '%constant' prefix. The python code which registers the callback, must be an unquoted string and refer to the C name.

See the code examples, in appendix A, for the modifications to each file.

If you run fd2python --makefile app you will get a template makefile program called app.makefile. This make file will work without any modifications. This makefile contains all the rules to run swig and compile all the C files and build a dynamic linkable python shared object file so that you python application will run.

mv app.makefile Makefile
make

APPENDIX A

CODE SNIPPITS for item 3 under 'ADDING NEW CALLBACK ROUTINES'

In app_my_main.py:

obj = fl_add_button(FL_NORMAL_BUTTON, 100, 100, 140, 40, "Close");
fl_set_object_callback(obj, DO_CLOSE_BUTTON, 0);

In app.i:
#
# Automatically generated by 'fd2python --callback'
#
%module apwrap
%include "forms.i"
%{
#include <forms.h>
void DO_CLOSE_BUTTON (FL_OBJECT *obj, long arg);
void C_EXIT (int code);
%}
%constant void DO_CLOSE_BUTTON (FL_OBJECT *obj, long arg);
void C_EXIT (int code);

In app_cb.py:

#
# Automatically generated by 'fd2python --callback'
#
from appwrap import *
import __main__
import sys
# Note: For some reason, the sys.exit(0) call doesn't work. It returns back
# to the C routine that called the python routine.
def do_close_button(obj, arg):
C_EXIT(0)

In app_cb.c:

/*
* Automatically generated by 'fd2python --callback'
*/
#include <forms.h>
void call_python (char *method, FL_OBJECT *obj, int arg);
/*
* Note: for some reason, the sys.exit(0) call does not work. It returns back
* to the C routine that called the python routine.
* You must use 'exit(0)' from a C routine.
*/
void C_EXIT(int code)
{
exit(code);
}
void DO_CLOSE_BUTTON (FL_OBJECT *obj, long arg)
{
call_python("do_close_button", obj, arg);
}
------------------- cut -------------------------