# pyFLTK - Python Module for the FLTK GUI Toolkit

- NAME
- DESCRIPTION
  - What's in this document?
  - Using pyFltk
  - Using callbacks
  - Interactive usage
- EXAMPLES
- ACKNOWLEDGEMENTS
- AUTHORS
- SEE ALSO

# NAME

pyFltk - Python module for the FLTK GUI toolkit.

# DESCRIPTION

FLTK

FLTK is a toolkit for creating GUI applications for UNIX/X11, MS Windows and Mac. This module allows you to write programs with this toolkit in Python without the fuss of C++. FLTK was created by Bill Spitzak and can be found on the web at http://www.fltk.org.

## What's in this document?

This document will not cover all the details on using the FLTK toolkit. For complete instructions on the FLTK API consult the manual that comes with the source code or see the latest manual on the FLTK website. This document will cover the differences in using pyFLTK and provide some examples.

## Using pyFltk

The Python syntax for FLTK is very similar to using it in C++. To declare a new window, simply use:

            window = Fl_Window( width, height, label)

As FLTK takes posession of all the widgets that are created, the Python garbage collector will attempt to delete widgets that have already been deleted by FLTK, or vice-a-versa. To avoid this, `thisown` is internally set to 0 for every created widget. If it is necessary to explicitly delete a window, then `thisown` has to be set to 1, prior to deleting.

All widgets are declared in a similar manner. After a new window or group is declared all widgets declared after it will be inserted into it until the `end()` member function is called. This is the same as using the C++ API, so consult the FLTK documentation for further info.

## Using callbacks

Callbacks do the work of your program. To get a widget to respond to events sent to it you must assign a callback function to it. This is done using the `callback(sub-name, data)` function:

            def button_cb(ptr, data):
    	    btn = castWidget2Button(ptr)
                # do something

    	.
            .
            .
            button = Fl_Button(10, 10, 40, 20, "Button")
            button.callback(button_cb, "I am a button")
            .
            .
            .

Note the cast in the callback function. This corresponds and indeed wraps a C++ dynamic cast and allows to access the actual type of the widget. In case that the proper type cast is not avaliable or that such a construct is deemed unpythonic, global identifiers should be used instead.

## Interactive usage

(Courtesy of Michiel de Hoon)
Interactive behavior is particularly useful for rapid development of GUIs, for beginning users of pyFltk, as well as for scientific visualization.
As an example, the following will work:

            > python
            >>> from fltk import *
            >>> window = Fl_Window(300,300)
            >>> window.end()
            >>> window.show()
            # Window pops up here
            >>> window.label("My new title")
            # Window label changes immediately
            >>> window.color(FL_RED)
            >>> window.redraw()
            # Window color changes to red immediately

... and so on, all without calling Fl.run().

# EXAMPLES

Here's some quick example scripts to get you going, starting with the ubiquitous Hello World:

            from fltk import *
            import sys

            def btn_cb(ptr):
                sys.exit(0)

            window = Fl_Window(200, 90, "hello.py")
            button = Fl_Button(9, 20, 180, 50, "Hello World")
            button.callback("btn_cb")
            window.end()
            window.show()

            Fl.run() #starts the event loop

# ACKNOWLEDGEMENTS

            Bill Spitzak <spitzak@cinenet.net> FLTK Author
            Micheal Sweet <mike@easysw.com> FLTK Maintainer
    	Kevin Dahlhausen <morse@harborcom.net> Originator of pyFltk
    	Matt Kennedy <mkennedy@odysseys.net> Originator of Perl FLTK module

# AUTHORS

            Andreas Held <a.held@computer.org> Python FLTK module

# SEE ALSO

            The FLTK Manual. Available at http://www.fltk.org
            pyFltk homepage at http://pyfltk.sourceforge.com