Skip to content
vmagnin edited this page Mar 26, 2019 · 384 revisions

Introduction | Quick start guide video | Citing gtk-fortran | News | gtk-fortran structure | Installation and building | Using gtk-fortran | Learning GTK | How can I help ? | History and Roadmap | Tools used in this project | Licenses

Introduction

The gtk-fortran project aims to offer scientists programming in Fortran a cross-platform library to build Graphical User Interfaces (GUI), licensed under GNU GPL 3. Gtk-fortran is a partial GTK / Fortran binding 100% written in Fortran, thanks to the ISO_C_BINDING module for interoperability between C and Fortran, which is a part of the Fortran 2003 standard. It offers interfaces to around 10000 GTK 2 and GTK 3 functions (GTK, GDK, GdkPixbuf, Cairo, Pango, ATK, GLib, GObject, GIO). Although mainly developed under Linux, you can easily use it under Windows via MSYS2. It runs also under UNIX systems like BSD and macOS.

GTK being a huge library, only some hundreds of its functions have been tested. That is the reason why gtk-fortran should be considered as eternally in the alpha development stage. See the list of Tested functions and the Status page for more informations.

Note that gtk-fortran goes beyond programming GUI:

  • GTK includes the crossplatform GLib library which offers a lot of generic functions (regular expressions, random numbers, hash, strings, input/output...),
  • and gtk-fortran offers also an interface to PLplot.

You can join our small community to share knowledge, skills and code: just create a github account and you will be able to post messages and make pull requests. Every good will is welcome (see the How can I help ? section at the end of the page).

Quick start guide video

In this video, you will see how to install and build gtk-fortran and its examples in five minutes: gtk-fortran video tutorial

You will find some screenshots on the wiki and more in the screenshots directory (especially in the gtk3 branch). You can also watch this short video under MacOS posted by a gtk-fortran user. You can also have a look at the list of projects using gtk-fortran.

Citing gtk-fortran

gtk-fortran is entirely free (as in free beer and freedom), but you can cite this paper:

Vincent MAGNIN, James TAPPIN, Jens HUNGER, Jerry DE LISLE, "gtk-fortran: a GTK+ binding to build Graphical User Interfaces in Fortran", Journal of Open Source Software, 4(34), 1109, 12th January 2019, https://doi.org/10.21105/joss.01109

DOI

News

  • 2019-03-14: PLplot>=5.13 is now required (gtk3 branch). Tested under Ubuntu 18.10, Fedora 29 and MSYS2 / Windows 7, FreeBSD 12.0, Manjaro 18.0.2, Gentoo 201808, openSUSE 15.0. The documentation has been revised. The master (GTK 2) branch keeps PLplot<=5.10.
  • 2019-03-08: gtk-fortran (gtk3 branch) can now use parallel building using make -j or make --jobs. On some systems, like FreeBSD, the number of jobs must be given: make -j 4 for example. See the GNU Make documentation for more information.
  • 2019-02-08: the default branch is now gtk3. The master (gtk2) branch should not be used for new projects.
  • 2019-02-04: you can not build PLplot examples with PLplot >=5.11 versions because of major changes in that library. Updated 2019-03-12: Fixed
  • 2019-01-19: following an ownership transfer, the gtk-fortran repository URL is now https://github.com/vmagnin/gtk-fortran. The URL https://github.com/jerryd/gtk-fortran is automatically redirected to the new URL. So it is transparent to the user. You are not obliged to modify it in your git settings, but if you want, type: git remote set-url origin git@github.com:vmagnin/gtk-fortran.git
  • 2018-05-01: gtk-fortran 17.10 released
    • v17.10.gtk2.24.31: based on GTK+ 2.24.31, GLib 2.54.1, PLplot 5.10 and generated with Kubuntu 17.10,
    • v17.10.gtk3.22.25: based on GTK+ 3.22.25, GLib 2.54.1, PLplot 5.10 and generated with Kubuntu 17.10.

Older news

gtk-fortran structure

gtk-fortran is a three-stage rocket:

  • its developers use the src/cfwrapper.py script to parse the GTK .h header files and automatically generate the src/*-auto.f90 files containing interfaces to the functions of the GTK libraries. Normally, you should not use cfwrapper.py except if you know what you do.
  • The src/gtk.f90 and the src/*-auto.f90 files constitute the sources of the gtk-fortran interface. You can use all their functions to create your graphical user interface in your own program.
  • But you can also decide to use the gtk_hl high level interface for gtk-fortran (src/hl-*.f90 files) which offers a simplified interface to the most useful GTK functions.

The project offers also some tools, as the gtkf-sketcher, and many examples to help you learn and use gtk-fortran and GTK.

Installation and building

Git branches and tagged releases

You will find the current versions of gtk-fortran in the gtk3 branch for GTK 3 and master branch for GTK 2 (use gtk3 for new projects).

If you have an older version of GTK 2 or GTK 3 on your system, you should have no problem because deprecated functions are removed only in the next major versions of GTK. But in GLib, deprecated functions are sometimes removed from one minor version to another, which can prevent building gtk-fortran on your machine. In that case, you can test an older tagged release by choosing one in the "Switch branches/tags" selection window. We create a new tagged release each time the cfwrapper.py script is used to wrap a new GTK version.

Dependencies

First, you need a Fortran compiler with the ISO_C_BINDING module, i.e. compliant with the Fortran 2003 standard, for example gfortran which is mainly used to develop gtk-fortran. You also need the GTK development files and the CMake building system. If you want to build the PLplot examples, you need the PLplot development files and the PLplot Cairo driver.

Downloading gtk-fortran

If you have a github account, you can simply clone the repository using git:

$ git clone git@github.com:vmagnin/gtk-fortran.git

or you can click in your browser on the Code tab (top left), then click on the Clone or download button on the right, then click on Download ZIP and extract the files in your home directory.

Linux

In a Debian based distribution like Ubuntu you need:

$ sudo apt install gfortran libgtk2.0-dev libgtk-3-dev

Depending on your distribution, you may also need other packages, for example the development files for other GTK libraries like GDK, GdkPixbuf, Cairo, Pango, ATK, GLib, GObject, GIO...

If you want to use PLplot in gtk-fortran:

$ sudo apt install libplplot-dev plplot-driver-cairo

Now, the best way to fully build gtk-fortran and install its libraries on your system is to use CMake:

$ sudo apt install cmake

You can then build the project from its top-level directory by typing:

$ mkdir build
$ cd build
$ cmake ..
$ make
$ sudo make install

Note that with gtk3, there is a cmake warning: -- Some or all of the gtk libraries were not found. (missing: GTK3_GDKCONFIG_INCLUDE_DIR) that appears harmless and is probably a failing of the FindGTK3.cmake file.

For parallel building use make -j or make --jobs.

If some examples causes a building error, you can ignore them with: make -i

CMake variables are set by using -D <variable>=<value>. For example to change the default install directory from /usr/local to /usr: cmake -D CMAKE_INSTALL_DIR=/usr .. And you can build in Debug mode using -D CMAKE_BUILD_TYPE=debug

Useful CMake variables that are specific to gtk-fortran are:

  • EXCLUDE_PLPLOT Set this to disable building the PLplot integration even if PLplot is found.
  • INSTALL_EXAMPLES Set this to install the source code of the examples into ${CMAKE_INSTALL_DATAROOTDIR/gtk-fortran/examples<gtkversion>, this would for example be useful if you were making a binary package of gtk-fortran.
  • NO_BUILD_EXAMPLES Set this to prevent compiling the example programs, also mostly useful for packagers.

To interactively control the build, use 'ccmake' in place of 'cmake'.

Sometimes it can help to clean out the build directory and re-run cmake:

cd build
rm -r *   ## MAKE SURE YOU ARE IN THE BUILD DIRECTORY BEFORE DOING THIS
cmake ..

A script with something like if [ "$(pwd | grep -e .*build$)" != '' ]; then rm -r *; else echo "Be careful !"; fi could be more secure...

Remove also the .mod files that could lie around in the gtk-fortran subdirectories if you have compiled something without using CMake.

Testing gkt-fortran

You can now test gtk-fortran by running the examples in the build/examples directory:

$ cd examples
$ ./gtkhello

If perl is installed on your machine, you can use the test/run_all.pl script to run them all one after the other:

$ cd test
$ ./run_all.pl ../build/examples

Alternative to CMake

If you really do not want to install CMake, you can alternatively use the src/test.sh bash script to compile and run all the gtk-fortran files and all examples, using gfortran by default (to use another compiler, use the following syntax: GFC='mycompiler' ./test.sh).

And if you know which gtk-fortran files are needed, you can also simply compile and run each example as follow, from the src/ directory:

$ gfortran glib-auto.f90 cairo-auto.f90 gdk-auto.f90 gdk-pixbuf-auto.f90 gtk.f90 ../examples/julia_pixbuf.f90 `pkg-config --cflags --libs gtk+-2.0`
$ ./a.out

(please replace 2.0 by 3.0 in the gtk3 branch).

Windows

The easiest way is to use MSYS2-MINGW64 and CMake:

  • Download, install and update as explained on the site MSYS2 (MSYS2 don't work anymore with Windows XP)
  • Install the following packages via MSYS2-MSYS shell:
    • build tools: $ pacman -S mingw-w64-x86_64-toolchain base-devel
    • cmake: $ pacman -S mingw-w64-x86_64-cmake
    • GTK 3 and dependencies: $ pacman -S mingw-w64-x86_64-gtk3 (and/or gtk2 if you need)
    • PLplot: $ pacman -S mingw-w64-x86_64-plplot mingw-w64-x86_64-qhull mingw-w64-x86_64-gd (optional)
    • Doxygen: $ pacman -S mingw-w64-x86_64-doxygen (optional)
  • Your MSYS2 directory size will be around 2 Gio.
  • Start MSYS2-MINGW64 shell.
  • Download gtk-3-fortran: $ wget https://github.com/vmagnin/gtk-fortran/archive/gtk3.tar.gz (or gtk2 if you need)
  • Extract gtk-3-fortran files: $ tar -xvzf gtk3.tar.gz
  • $ cd gtk-fortran-gtk3
  • $ mkdir build && cd build
  • Generate make files with cmake: $ cmake -G "MSYS Makefiles" .. (default on msys or mingw is "NMake Makefiles")
  • $ make
  • Note that in MSYS2, the building is several times slower than under Linux. But you can accelerate it with make -j for parallel building.
  • Launch the examples using command line: $ cd examples then $ ./gtkhello2 for example.

You can also use git in MSYS2:

  • In a MSYS2 shell, install git: pacman -S git (it will also install openssh and vim)
  • Put your keys in the .ssh directory.
  • git clone git@github.com:vmagnin/gtk-fortran.git
  • Start a MSYS2-MINGW64 shell to work.

FreeBSD

Tested in FreeBSD 12.0:

# pkg install git cmake gcc8 gtk2 gtk3

After cloning the directory:

$ cmake -D CMAKE_BUILD_TYPE=debug -D CMAKE_Fortran_COMPILER:FILEPATH="/usr/local/bin/gfortran8" ..
$ make
$ export LD_PRELOAD=/usr/local/lib/gcc8/libgcc_s.so.1
$ cd examples
$ ./gtkhello

The environment variable LD_PRELOAD is necessary if you have an error concerning ligcc_s.so.1.

For parallel building use make -j N or make --jobs N where N is the number of jobs.

In FreeBSD 12.0, the proposed PLplot version is 5.12. If you want ot use PLplot, you need to install PLplot>=5.13 from source using CMake:

$ export FC=/usr/local/bin/gfortran8
$ cmake -D CMAKE_INSTALL_PREFIX=/home/osboxes/myplplot ../plplot-5.14.0

then to build gtk-fortran with that command:

$ PKG_CONFIG_PATH=/home/osboxes/myplplot/lib/pkgconfig cmake ..

macOS

Search in the Issues tab to find messages from macOS users.

You can help us improve this part of the documentation by posting the commands needed to install and use gtk-fortran under macOS. We will put them here.

Using gtk-fortran

Which GTK functions can I use ?

The list of all the functions available in gtk-fortran, with informations on the required files and the C prototype of the function, is in the src/gtk-fortran-index.csv file.

Concerning the names of the modules you need, you can generally just look at the beginning of the names of the functions you use: gtk_window_new is in the gtk module, cairo_curve_to is in cairo... Note that historically the enumerators of all the libraries were placed in the gtk module.

Building your own GTK application

On Linux and Unix systems the build system generates a pkg-config file and installs it. So building a single source file application should be as simple as:

gfortran my_app.f90 $(pkg-config --cflags --libs gtk-3-fortran)

If you have made a default install to /usr/local you may need to run: export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig (Or setenv PKG_CONFIG_PATH /usr/local/lib/pkgconfig if you use csh or one of its derivatives). This will depend on your distribution, Ubuntu looks there by default, Pardus and Manjaro don't.

Advices to lower compilation time

gtk-fortran offering interfaces to around 10000 functions, you should add to your use statements the only: option to accelerate the compilation, e.g.:

use gtk, only: gtk_init, gtk_window_new, GTK_WINDOW_TOPLEVEL, &
      & gtk_window_set_title, gtk_container_set_border_width, &
      & g_signal_connect, gtk_hbox_new, gtk_container_add, &
      & gtk_button_new_with_label, gtk_box_pack_start, &
      & gtk_widget_show, gtk_main, FALSE, CNULL, TRUE

To help you, the usemodules.pl perl script can scan your Fortran source files for GTK and related library functions and generate the required use statements. For more informations type:

perl usemodules.pl --help

Known issues or limitations

Parsing more than 700 .h header files is not an easy task. So gtk-fortran can not implement 100% of GTK functions and constants and have some limitations:

  • gstdio.h and giochannel.h were excluded because some functions are declared twice (UNIX and non UNIX systems for example).
  • Around 135 functions with optional arguments (variadic fuctions) are not implemented. But these functions are often also available with an array argument to solve binding problems (for example gtk_list_store_new / gtk_list_store_newv). See http://live.gnome.org/GObjectIntrospection/WritingBindingableAPIs
  • Very few GTK types are not yet implemented.
  • Macro functions and constants (#define) are not implemented.
  • Structures (struct) are not implemented.
  • Some enums are missing, like GdkPixdataType.
  • Fortran has no unsigned integers, so problems could occur if you pass great values between Fortran and GTK. See the tests.f90 file.

See also the list of opened issues.

Learning GTK

You can begin by studying the examples available in the examples/ directory (gtk3 branch), beginning by gtkzero.f90 (just creates an empty GTK window) and gtkhello.f90 (a window with two buttons). Those simple examples are heavily commented in order to help you learn the GTK basics. If you want to draw progressively a picture pixel by pixel during a scientific computation, mandelbrot_pixbuf.f90 is a good starting point.

To understand the GTK event-driven programming model, read the Main loop and Events documentation page.

The following book, although quite old and based on GTK 2, is a good source to learn GTK:

Some external docs about gtk-fortran:

Some useful links:

How can I help ?

  • We need people building gtk-fortran under the more OS versions possible (particularly for Windows and macOS), for various architectures (32/64 bits, ARM...) and with various Fortran compilers. You can post the warnings or error messages obtained when building with cmake -D CMAKE_BUILD_TYPE=debug ..
  • You can report issues and ask support in the Issues tab.
  • You can work on fixing issues and make a Pull request.
  • You can write new examples or improve existing examples and make a Pull request. Note that the GTK official C examples are available in the applications gtk-demo and gtk3-demo (gtk-3-examples and gtk2.0-examples Ubuntu packages).
  • Put a link on your site to https://github.com/vmagnin/gtk-fortran/wiki, and include the "GUI" and "graphical user interface" keywords to improve our pagerank in search engines. And cite gtk-fortran in your papers: DOI

History and Roadmap

History

This project is based on Tobias Burnus' post on comp.lang.fortran newsgroup (2nd May 2007 13:10) where he gave an example of a Fortran 2003 program creating a minimalist GUI (an empty GTK window) using ISO_C_BINDING. Vincent Magnin posted a message on the 27th December 2010 and got into contact with Jerry DeLisle on the 29th. They launched together the project in January 2011. Other contributors then joined: James Tappin, Jens Hunger...

Gtk-fortran was soon referenced in the following book: Markus, Arjen. Modern Fortran in Practice. 1st ed. Cambridge: Cambridge University Press, 2012, http://dx.doi.org/10.1017/CBO9781139084796.

A paper was finally published in the Journal of Open Source Software in 2019.

Roadmap

Some projects using gtk-fortran

  • "The VCU nuclear reactor simulator, Richmond Pile 3, is a classroom and research tool that emulates a large commercial pressurized water reactor (PWR)." Tincher, D. and Bilbao y León, S. and Miller, J., "Progress on real-time, interactive modeling and simulation of nuclear power plants", 17th International Topical Meeting on Nuclear Reactor Thermal Hydraulics, NURETH 2017, September 2017.
  • UncertRadio 2. Kanisch G., "Generalized evaluation of environmental radioactivity measurements with UncertRadio. Part I: Methods without linear unfolding" (2016) Applied Radiation and Isotopes, 110, pp. 28-41, http://dx.doi.org/10.1016/j.apradiso.2015.12.003.
  • NetworkMaker Editor.
  • gPowDi: Powder Diffraction GUI.
  • RPN Scientific calculator
  • GRAFFER
  • Simply Fortran offers some gtk-fortran packages on their package server.

Tools used in this project

Licenses

Gtk-fortran is licensed under GNU General Public License version 3. The wiki documentation is under the GNU Free Documentation License 1.3. The gtk-fortran logo uses the GTK logo (by Andreas Nilsson) and so is also under GNU Free Documentation License Version 1.2 or later & Creative Commons Attribution-Share Alike 3.0 Unported license. Its font is DejaVu Sans, a font under a free license.

You can’t perform that action at this time.