c++-gtk-utils library

This is a lightweight library containing a number of classes and functions for programming GTK+ programs using C++ in POSIX (unix-like) environments, where the user does not want to use a full-on wrapper such as gtkmm or wxWidgets, or is concerned about exception safety or thread safety of the wrapper and their documentation.

The latest version of the library targetting C++98/03 (the 1.2 series) is version 1.2.45, and can be downloaded from http://sourceforge.net/projects/cxx-gtk-utils/files/cxx-gtk-utils/1.2.45/c++-gtk-utils-1.2.45.tar.gz/download .

The 1.2 series of the library can be compiled under C++98/03 and C++11/14. A separate 2.2 series of the library is available which targets C++11/14/17 only.

The library can be separately built (and parallel-installed) for both GTK+2 and GTK+3, and parallel installations can be separately queried for when configuring user programs for compilation, by means of c++-gtk-utils-1.2.pc (for GTK+2) and c++-gtk-utils-1.3.pc (for GTK+3). There is also an option to compile the library without GTK+ support, so only requiring glib. See GTK versions for further details.

It provides the following:

• Classes for managing the lifetimes of GTK+ widgets and windows which will make GTK+ exception safe (Cgu::WinBase and Cgu::MainWidgetBase)

• Classes for managing GObject reference counts (Cgu::GobjHandle) and GVariant reference counts (Cgu::GvarHandle), and for making weak references to GObjects (Cgu::GobjWeakHandle).

• A class for using Cgu::WinBase objects with GtkApplication/GApplication (Cgu::Application).

• High level classes for running parallel tasks which can be integrated with the glib main loop (Cgu::Thread::TaskManager, Cgu::Thread::Future).

• Functions to make single instance programs, where restarting will bring up the existing instance (Cgu::prog_present). This is an optional inclusion - it will only be compiled into the library if dbus-glib >= 0.70 or glib >= 2.26 is installed.

• Classes for using C++ standard iostreams with GIO streams (Cgu::gistream, Cgu::gostream, Cgu::giostream, Cgu::wgistream, Cgu::wgostream and Cgu::wgiostream) and with files opened with unix file descriptors (Cgu::fdistream, Cgu::fdostream, Cgu::wfdistream and Cgu::wfdostream).

• Classes for memory management (Cgu::SharedPtr, Cgu::SharedLockPtr, Cgu::SharedHandle, Cgu::SharedLockHandle, Cgu::ScopedHandle, Cgu::IntrusivePtr, Cgu::IntrusiveCounter, Cgu::IntrusiveLockCounter, Cgu::GcharScopedHandle, Cgu::GcharSharedHandle, Cgu::GerrorScopedHandle and Cgu::GerrorSharedHandle).

• Callback/closure classes for static and non-static member functions, and thread-safe signal/slot classes with automatic disconnection (Cgu::Callback::CallbackArg, Cgu::Callback::FunctorArg, Cgu::Callback::SafeFunctorArg, Cgu::EmitterArg, Cgu::SafeEmitterArg and Cgu::Releaser).

• A function for running arbitrary scheme script extensions within C++ programs using the guile VM (Cgu::Extension::exec() and Cgu::Extension::exec_shared()).

• Functions for connecting a Callback object and a unix file descriptor to the main loop, with provision for automatic disconnection (Cgu::start_iowatch()).

• Functions for connecting a Callback object and a timeout to the main loop, with provision for automatic disconnection (Cgu::start_timeout() and Cgu::start_timeout_seconds()).

• Classes and functions for inter-thread communication (Cgu::Notifier, Cgu::AsyncQueue, Cgu::AsyncQueueDispatch, Cgu::AsyncChannel, Cgu::AsyncResult and Cgu::Callback::post()).

• Some convenience pthread wrapper classes (Cgu::Thread::Thread, Cgu::Thread::JoinableHandle, Cgu::Thread::Mutex, Cgu::Thread::Cond, Cgu::Thread::Mutex::Lock, Cgu::Thread::Mutex::TrackLock, Cgu::Thread::RecMutex, Cgu::Thread::RecMutex::Lock, Cgu::Thread::RecMutex::TrackLock, Cgu::Thread::RWLock, Cgu::Thread::RWLock::ReaderLock, Cgu::Thread::RWLock::ReaderTrackLock, Cgu::Thread::RWLock::WriterLock, Cgu::Thread::RWLock::WriterTrackLock, Cgu::Thread::Exit and Cgu::Thread::CancelBlock), and a scoped locking class (Cgu::Thread::GrecmutexLock) for use with a GStaticRecMutex object (that is, where a recursive mutex is wanted but the native pthread implementation does not itself support recursive mutexes).

• A class encapsulating anonymous unix pipes (Cgu::PipeFifo), and for synchronising between processes when setting up (Cgu::SyncPipe).

• A class for reassembling UTF-8 strings sent over pipes and sockets so they form complete valid UTF-8 characters suitable for GTK+ widgets (Cgu::Utf8::Reassembler).

• Functions for converting between character sets, including between wide and narrow Unicode representations (Cgu::Utf8::uniwide_from_utf8(), Cgu::Utf8::uniwide_to_utf8(), Cgu::Utf8::wide_from_utf8(), Cgu::Utf8::wide_to_utf8(), Cgu::Utf8::filename_from_utf8(), Cgu::Utf8::filename_to_utf8(), Cgu::Utf8::locale_from_utf8(), Cgu::Utf8::locale_to_utf8(), Cgu::Utf8::validate()), and iterator classes for iterating through a std::string object by UTF-8 character rather than by bytes (Cgu::Utf8::Iterator, Cgu::Utf8::ReverseIterator).

• Classes for printing postscript files (Cgu::FilePrintManager) and plain text (Cgu::TextPrintManager) using the GTK+ print system.

• Functions to provide templated type-selected conditional compilation (Cgu::DoIf::mem_fun() and Cgu::DoIf::fun()), and utilities for static type assertion (Cgu::DoIf::assert_related_to_type(), Cgu::DoIf::assert_related_types(), Cgu::DoIf::assert_same_type() and Cgu::DoIf::assert_not_const()).

• A utility adaptor to create a functor to execute a class member function on items contained by standard containers, equivalent to std::ptr_fun() for ordinary functions (Cgu::MemFun::make()).

Note

1. Certain parts of this library would (if compiled for windows with a suitable build system) work under windows without cygwin, such as the classes for managing object lifetime and memory management (including the locked shared pointer class as that uses glib atomic functions by default), the iostreams for GIO, the iostreams for file descriptors as regards their use with winsock sockets (with changes to the headers), the utf8 utilities, the text print manager, the memfun utility adaptor and the callback/closure classes, including the callback posting function for inter-thread communication. (The thread-safe signal/emitter classes could not be used under windows without rewriting the mutex locking to use GMutex or windows critical sections.)

2. This library is released under the GNU Lesser General Public License version 2.1. Where a header file or template file in the library provides a templated class or function or inline function or macro, the licence is modified to provide an exception for the template, inline function or macro in the following terms: 'However, it is not intended that the object code of a program whose source code instantiates a template from this file or uses macros or inline functions (of any length) should by reason only of that instantiation or use be subject to the restrictions of use in the GNU Lesser General Public License. With that in mind, the words "and macros, inline functions and instantiations of templates (of any length)" shall be treated as substituted for the words "and small macros and small inline functions (ten lines or less in length)" in the fourth paragraph of section 5 of that licence. This does not affect any other reason why object code may be subject to the restrictions in that licence (nor for the avoidance of doubt does it affect the application of section 2 of that licence to modifications of the source code in this file).'

3. From version 1.2.0, the library is placed in the Cgu namespace, but if the --with-cgu-using-directive configuration option is passed to ./configure, a 'using namespace Cgu' directive is placed in each of the library headers to maintain source compatibility with earlier versions of the library. See Namespace Cgu for further details.

4. The library may be configured, with the --with-glib-memory-slices-compat or --with-glib-memory-slices-no-compat configuration options, so that where objects from the library are constructed on free store, they are constructed in memory allocated with glib memory slices. See Memory allocation for further details.

5. From version 1.2.3, the library can be separately built and parallel-installed for both GTK+2 (version >= 2.10) and GTK+3 (version >= 2.90.0), and parallel installations can be separately queried for when configuring user programs for compilation by means of c++-gtk-utils-1.2.pc (for GTK+2) and c++-gtk-utils-1.3.pc (for GTK+3). There is also an option to compile the library without GTK+ support, so only requiring glib. See GTK versions for further details.

6. The ChangeLog can be viewed at: http://cxx-gtk-utils.sourceforge.net/1.2/ChangeLog

7. The current files in git can be viewed at: http://sourceforge.net/p/cxx-gtk-utils/git/ci/v1_2/tree/ in the v1_2 branch, and can be obtained with:

git clone git://git.code.sf.net/p/cxx-gtk-utils/git

Then go into the origin/v1_2 branch, and run './bootstrap-gtk2.sh', './bootstrap-gtk3.sh', '.configure' and 'make docs' for a complete distribution, or clone the remote repository directly over the top of the latest release for the 1.2 series.

8. There is a mailing list concerning the use or development of the library at http://lists.sourceforge.net/lists/listinfo/cxx-gtk-utils-general/

The author can be contacted at: cvine -at- users -dot- sourceforge -dot- net