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 in the 2.2 series of the library is version 2.2.20, and can be downloaded from http://sourceforge.net/projects/cxx-gtk-utils/files/cxx-gtk-utils/2.2.20/c++-gtk-utils-2.2.20.tar.gz/download .

This 2.2 series of the library is only for use with C++11/14/17. If using gcc, gcc-4.6 or later is required. In addition, it will compile with clang-3.4 or later. If using gcc-4.4, gcc-4.5 or clang-3.3 with C++0x/11, use the 2.0 series of this library. The 1.2 series of the library is available for use with C++98/03 and earlier versions of gcc or clang, and can also be compiled under C++11/14.

If using gcc-4.6 or 4.7.0 user code must be compiled with the -std=c++0x compiler flag. gcc-4.7.1 onwards accepts either the -std=c++0x or -std=c++11 compiler flag, as does clang-3.4. For those compilers which support it, user code can also be compiled with the -std=c++14 and -std=c++17 flags.

The library can be separately built (and parallel-installed) for GTK-2, GTK-3 and GTK-4, and parallel installations can be separately queried for when configuring user programs for compilation, by means of c++-gtk-utils-2-2.2.pc (for GTK-2), c++-gtk-utils-3-2.2.pc (for GTK-3) and c++-gtk-utils-4-2.2.pc (for GTK-4). 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), and parallel computation functions for containers Cgu::Thread::parallel_for_each(), Cgu::Thread::parallel_for_each_partial(), Cgu::Thread::parallel_transform(), Cgu::Thread::parallel_transform_partial(), Cgu::IntIter).

• 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, Cgu::wgiostream, Cgu::u32gistream, Cgu::u32gostream, Cgu::u32giostream, Cgu::u16gistream, Cgu::u16gostream and Cgu::u16giostream) and with files opened with unix file descriptors (Cgu::fdistream, Cgu::fdostream, Cgu::wfdistream, Cgu::wfdostream. Cgu::u32fdistream, Cgu::u32fdostream, Cgu::u16fdistream and Cgu::u16fdostream).

• 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 type erasure, 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::utf32_from_utf8(), Cgu::Utf8::utf32_to_utf8(), Cgu::Utf8::utf16_from_utf8(), Cgu::Utf8::utf16_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 enable std::tuple objects to be expanded into their component elements in order to pass those elements to functions as arguments on function calls (Cgu::tuple_apply()).

• 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 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. 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 versions of the library prior to version 1.2.0. 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. The library can be separately built and parallel-installed for GTK-2 (version >= 2.10), GTK-3 (version >= 2.90.0) and GTK-4 (version >= 3.98.4), and parallel installations can be separately queried for when configuring user programs for compilation by means of c++-gtk-utils-2-2.2.pc (for GTK-2), c++-gtk-utils-3-2.2.pc (for GTK-3) and c++-gtk-utils-4-2.2.pc (for GTK-4). 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/2.2/ChangeLog

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

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

Then run './bootstrap-gtk2.sh', './bootstrap-gtk4.sh', ./bootstrap-gtk3.sh' and 'make docs' (in that order) for a complete distribution, or clone the remote repository directly over the top of the latest release for the 2.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