Gintro

= High level GTK4 and GTK3 bindings for the Nim programming language //(c) Stefan Salewski
//Version 0.9.9 :experimental: :imagesdir: http://ssalewski.de/tmp //:source-highlighter: pygments //:pygments-style: monokai :source-highlighter: rouge :rouge-style: molokai :icons: font :toc: left

:GIR: GObject-Introspection :MAC: MacOSX

//(c) Stefan Salewski + //2018

TIP: A more fancy copy of this document with dark source code background is available at http://ssalewski.de/gintroreadme.html[GIntro README] This document describes mainly the use of these bindings for GTK3. For GTK4 you may also consult the pre-print of the Nim GTK4 book located at http://ssalewski.de/gtkprogramming.html.

WARNING: Please do not use the code from the examples in this page, but use the actual code from https://github.com/StefanSalewski/gintro/tree/master/examples . The github readme.adoc does not allow to insert code from files, so I had to manually insert it, and so that code in the html page may not compile with latest gintro version. I plan to create a new page hosted somewhere else with code inserted from files directly.

NOTE: This work is partly based on earlier works of J. Mansour and has been supported by E. Bassi and other GTK/Gnome developers. The combinatorics module was kindly provided by R. Behrends.

NOTE: As we have already reached version 0.9.9, we have stopped doing releases for now. So you should do a #head install with "nimble uninstall gintro; nimble install gintro@#head" to get an up to date version.

NOTE: This is finally version 0.9.9 of the gintro Nim GTK bindings. It contains some small fixes, that we applied in the last months. Note that gintro's version numbers are unsigned integers and so wrap around, so whenever there should be one more new release, that may get the tag 0.1 again. (More seriously, we hesitate to call next gintro version 1.0 already, because 1.0 would indicate some final state, which gintro can never archive. All the GTK related libraries are so complex, that it is nearly impossible to create perfect bindings.) But as the number of serious gintro users is tiny, we may fully remove gintro from GitHub by end of 2022. This will save us some work of continous bug fixes, and users can choose one of the 20 other Nim GUI toolkits. It is indeed very questionable if gintro would work with Nim 2.0 or GTK 5.0 at all. And after having worked on gintro for more than 1600 hours, it may be a good decision to just retire now.

NOTE: Version 0.9.8 of the gintro Nim GTK bindings contains some small fixes, including a fix for the latest uref/unref name change in gobject.

NOTE: In version 0.9.7 of the gintro Nim GTK bindings we tried to fix an issue resulting from use of symbols without a module prefix in the code generated by the mconnect() macro. See https://github.com/StefanSalewski/gintro/issues/188. Unfortunately this fix may break some existing projects. We tried hard to make changes as tiny as possible: We tried to let the content of the generated modules unchanged, and changed only files gimplgob.nim and gen.nim and the generated gisup4.nim and gisup3.nim files. The example programs still compile and seems to run.

NOTE: In version 0.9.6 of the gintro Nim GTK bindings we tried to fix a bug related to the appearance of libsoup 3.0. When gobject-introspection was first processing libnice, it loads old libsoup 2.4 and when then processing linsoup 3.0 name conflicts lead to error messages and the install process hung. Now we process always libsoup in version 2.4 and 3.0 before libnice, this seems to work. For libsoup 2.4 we generate a module called libsoup.nim as before, and the libsoup 3.0 module is now called libsoup3.nim.

NOTE: For version 0.9.5 of the gintro Nim GTK bindings we added a patch to support very old GTK3 versions like Debian Buster, updated the list of "light symbols" like Rectangle, TextIter and such that do not need Nim Proxy objects, and finally fixed a recent glib proc name conflict.

NOTE: Version 0.9.4 of the gintro Nim GTK bindings contains a lot of fixes. Before 0.9.4 some GtkDrawingArea examples gave crashes with the most recent Nim compiler due to a wrong cast from ref object to RootRef. That is fixed, and the drawingarea example works now also without manually freeing cairo resources like Context, Surface and Pattern. We have not updated the example, so it still contains the manually memory management, but you can comment it out if you want. When you compile your code with --gc:arc you really should not have to care for releasing cairo resources. If you still use the default refc GC you may release cairo resources manually, as the GC has a delay, which may first allocate some GB before the GC becomes active and frees the cairo resources. Note that only a small part of all the cairo functions has been tested yet, so there may still be bugs. Strings are now passed to GTK functions as cstrings, so you can pass nil as well as empty strings. The nil value has for GTK in most cases a special meaning and is different from an empty "" string. For some function parameters nil is the default value for cstrings. Finally we support now named empty flag sets, so instead of passing the empty set as {} for default flag set values you can use names like BindingFlagsDefault or BindingFlags.default.

NOTE: Version 0.9.3 of the gintro Nim GTK bindings contains some serious changes following the discussion in https://discourse.gnome.org/t/get-ref-function-for-none-gobject-classes-like-gtkexpression/6696. With that changes issue https://github.com/StefanSalewski/gintro/issues/135 should be fixed, and the listview_clocks example works with a C and a Nim part. For most apps that changes should be invisible, but it is possible that we have introduced new bugs or maybe memory leaks. At least the existing examples seems still to compile, but we have not yet tested them all. //You can test this version with nimble install gintro@#head. And the notify signals for gobject properties like "notify::cursor-moved" for entry widgets should work now.

NOTE: The version 0.9.2 of the gintro Nim GTK bindings is only a fix for the issue with latest gstreamer from gitlab, see https://github.com/StefanSalewski/gintro/issues/138.

NOTE: Version 0.9.1 is mostly a plain fix for issue https://github.com/StefanSalewski/gintro/issues/133. For GObject proc parameters with direction in and transfer full we have to avoid that the Nim memory management destroys the GObject when the Nim proxy object is destroyed. Current fix was adding a plain ".ignoreFinalizer = true" for that case, which works in most cases. But maybe a better fix would be to ref() the gtk object instead. Maybe that makes no difference for gobjects, but it can make a difference for entities like GtkExpression which are used further, see issue https://github.com/StefanSalewski/gintro/issues/137. But we will leave that for next version 0.9.3.

NOTE: Due to a user request we added support for the adwaita library for version 0.8.9. This lib is the libhandy variant for GTK4 and is intended to support GTK on mobile devices. Unfortunately we can not yet provide an example program for this library. The C example from git sources is not really tiny, so porting to Nim would take some hours at least, as we have absolutely no knowledge about that lib yet. Maybe we can provide an example next year or maybe that user will finally provide something?

NOTE: Starting with version 0.8.8 of the gintro Nim GTK bindings for procs like getStartIter() without a result but with a var out parameter an overloaded version is created where the var out parameter is returned as result. So we can write "let startIter = buffer.getStartIter()" now. And we tried to fix the issues with out gobject parameters as in g_file_new_tmp().

NOTE: For version 0.8.7 of the gintro Nim GTK bindings we did a larger internal cleanup for the gen.nim generator script but tried to generate output modules identical to v.0.8.6 still. For next release v0.8.8 there will be some changes in the generated modules then. Also for this version 0.8.7 we do support webkit2 for GTK4.

NOTE: Version 0.8.6 of the gintro Nim GTK bindings contains now all the standard gst modules, and due to a recent request also the gtklayershell.nim module. Due to issues with some gst modules we do now call init() for the gst module before we use it with gobject-introspection. We do the same for GTK3 and GTK4 as these provide also an init() proc. According to a recent discussion with the GTK core devs that init() call is necessary. The call is done by use of dlopen(), for which we need to provide the names of the dynamic libraries, which is some guesswork for Windows and Mac.

NOTE: For version 0.8.5 of the gintro Nim GTK bindings we have added webkitgtk support. Unfortunately still only for GTK3, as the latest webkitgtk package 2.30.4 does not compile with stable GTK4. But we should get webkitgtk for GTK4 in a few weeks. One question is still how to name the GTK4 version then. The official name of the version for GTK3 is webkit2, so shall we call the version for GTK4 webkitgtk4 or webkit4? Or different?

NOTE: Since version 0.8.4 we do support the libnice module for Linux and Windows. And we added gtksourceview5 to support gtksourceview usage for GTK4. The module is called gtksourceview5 because the underlying C library has mayor version 5 already. So you can write your own GTK4 Nim editor now. Additional optional var out parameters are supported now and GtkGestures should work also.

NOTE: The version gintro v0.8.3 will have some internal cleanup, which removes the temporary Array types. In the past we used that names to indicate array parameters, it was working well, but still it was ugly using names to indicates data types. So we fixed that. And we have added some better support for GList parameter. GLists are now converted to Nim seqs and vice versa. Not everywhere still, and this conversi