c++-gtk-utils Git
Brought to you by:
cvine
Menu
▾
▴
Tree [0d000b] master / History
Read Me
INTRODUCTION
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.
This 2.2 series of the library is only for use with C++11/14/17. The
1.2 series of library is available for use with C++98/03 and C++11/14.
It provides the following:
Classes for managing the lifetimes of GTK widgets and windows which
will make GTK exception safe.
Classes for managing GObject and GVariant reference counts and
GObject weak references.
A class for using Cgu::WinBase objects with
GtkApplication/GApplication.
High level classes for running parallel tasks which can be
integrated with the glib main loop, and parallel computation
functions for containers.
Functions to make single instance programs, where restarting will
bring up the existing instance.
Classes for using standard C++ iostreams with GIO streams and with
files opened with unix file descriptors.
General smart pointer classes for memory management.
Callback/closure classes for type erasure, and thread-safe
signal/slot classes with automatic disconnection.
Functions for running arbitrary scheme script extensions within C++
programs using the guile VM.
Functions for connecting a Callback object, a unix file descriptor
and a timeout to the main loop, with provision for automatic
disconnection.
Classes and functions for inter-thread communication.
Some convenience pthread wrapper classes, including mutexes, locks
and condition variables.
A class encapsulating anonymous unix pipes.
A reassembler class for sending UTF-8 text over pipes and sockets.
Functions for converting between codesets (including between narrow
and wide encodings) and classes for iterating through a std::string
object holding a UTF-8 string.
Classes for printing postscript files and plain text using the GTK
print system.
Functions to provide templated type-selected conditional
compilation, and utilities for static type assertion
DEPENDENCIES
The library requires:
glib >= 2.10.0
gtk-2.0 >= 2.10.0, gtk-3.0 >= 2.90.0 or gtk-4.0 >= 3.98.4 (unless
compiled with the --without-gtk option).
dbus-glib >= 0.70 if glib < 2.26 installed (optional - if not
installed then the single instance program facility will not be
built unless glib >= 2.26 is installed).
A functioning standard C++ library and compiler which is C++0x or
later compliant. If using gcc, gcc-4.6 or later is required. In
addition, this library 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. For C++98/03 or earlier versions of gcc or
clang, use the 1.2 series, which can also be compiled under
C++11/14. (Note however that only the 2.2 series supports GTK-4.)
A functioning POSIX library conforming to IEEE Std 1003.1-2001,
including pthreads (although earlier versions will probably work
provided the pthreads implementation is reasonably complete).
To configure the library for compilation, autoconf >= 2.59c and
pkgconfig >= 0.9 are required.
Note: If using gcc-4.6 or 4.7.0, code using this library should 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.
INSTALLATION
To compile:
./configure (or ./configure-gtk2 or ./configure-gtk4)
make
make install (as root)
In relation to use with GTK-2 or GTK-4, or without GTK entirely, see
further under 'GTK versions' below.
To choose a prefix other than /usr/local, use the --prefix option with
./configure, ./configure-gtk2 or ./configure-gtk4. Whatever prefix is
chosen, to use the library as installed make sure that
${prefix}/lib/pkgconfig is included in the PKG_CONFIG_PATH
environmental variable so that it can be found.
There are two configuration options which may be chosen concerning
memory allocation. By default, where objects from library classes are
constructed on free store, they are created using the global operator
new()/new[]() functions. However, glib memory slices provide an
efficient small object allocator (likely to be significantly more
efficient than global operator new/new[]), and if the
--with-glib-memory-slices-compat or
--with-glib-memory-slices-no-compat compilation configuration options
are chosen when './configure' or './configure-gtk2' is run, such
classes will be constructed in glib memory slices. If the
--with-glib-memory-slices-compat option is chosen, binaries which were
originally compiled against this library as installed with a default
configuration will continue to link and run correctly. However, if
the --with-glib-memory-slices-no-compat option is chosen, the library
will use glib memory slices more aggressively and any programs
compiled against the library as installed without that option will
need to be recompiled.
If you want to use glib memory slices, choose
--with-glib-memory-slices-no-compat unless you want to avoid having to
recompile programs already compiled against c++-gtk-utils in a case
where c++-gtk-utils was installed without that compilation option.
For these compatibility reasons, if the following classes are
constructed in freestore, they will only be constructed in glib memory
slices with the --with-glib-memory-slices-no-compat option:
Callback::CallbackArg<> and derivatives, WinBase and derivatives,
FilePrintManager, TextPrintManager, Thread::Mutex and Thread::Thread.
The following objects will never be constructed in glib memory slices
even if that option is chosen: GobjHandle, GobjWeakHandle, GvarHandle,
SharedPtr, SharedLockPtr, SharedHandle, SharedLockHandle, ScopedHandle
and IntrusivePtr (because, whilst such objects can be constructed on
free store, that would be highly unusual), IntrusiveCounter and
IntrusiveLockCounter (because it is for the derived class to decide
policy on how it should be allocated) and any built in types (such are
char arrays or strings) returned by library functions to the user. In
addition, where a library class uses a standard C++ container in its
implementation, it does not pass the container a glib-memory-slice
implemented allocator (in-container memory allocation will normally
have been optimized by the standard C++ library implementation).
The whole library (including its modular namespaces) is placed in the
Cgu namespace. However, if the --with-cgu-using-directive
configuration option is passed to ./configure or ./configure-gtk2,
each of the library headers has a 'using namespace Cgu' using
directive included within it in order to maintain source compatibility
for code written against previous versions of the library prior to
version 1.2.0.
From version 2.0.0-rc2, the library provides operator==(),
operator!=() and operator<(), and from version 2.0.0-rc3 provides
std::hash specializations, for comparisons of GobjHandle, GvarHandle,
IntrusivePtr, SharedHandle, SharedLockHandle, SharedPtr and
SharedLockPtr objects, to enable them to be more easily looked up in
containers and to enable them to be used as keys in ordered or
unordered associative containers. To prevent double definition errors
if the library user code provides its own operators and/or
specializations, these library provided ones can be omitted by
compiling the library with the --without-smart-pointer-comp or
--with-smart-ptr-comp=no configuration option.
GTK VERSIONS
As the tarball has been prepared, a call to './configure' will by
default configure the library for GTK-3. However if
'./configure-gtk2' or './configure-gtk4' is called, then the library
will be prepared for compilation against GTK-2 or GTK-4 respectively.
To configure and compile for GTK-2, GTK version 2.10.0 or greater is
required. To configure and compile for GTK-3, GTK version 2.90.0 or
greater is required. Version 2.99.0 or greater is required for the
Cgu::Application class to be compiled in. To configure and compile
for GTK-4, GTK version 3.98.4 or greater is required.
The compilation default can be changed to GTK-2 or GTK-4 by calling
'./bootstrap-gtk2.sh' or './bootstrap-gtk4.sh'. If so changed, to
compile the library then against GTK-3 it is necessary to call
'./configure-gtk3'. To change the default back to GTK-3 again, call
'./bootstrap-gtk3.sh'.
However the default is set, the library can always be explicitly
prepared for compilation against GTK-2 by calling './configure-gtk2',
against GTK-3 by calling './configure-gtk3' and against GTK-4 by
calling './configure-gtk4'. It will therefore not generally be
necessary to call bootstrap-gtk2.sh, bootstrap-gtk3.sh or
bootstrap-gtk4.sh.
The library as compiled for GTK-2, GTK-3 and GTK-4 can be parallel
installed. To configure a user program to link against the library as
installed for GTK-2 use c++-gtk-utils-2-2.2.pc, to configure to link
against the library as installed for GTK-3 use c++-gtk-utils-3-2.2.pc,
and to configure to link against the library as installed for GTK-4
use c++-gtk-utils-4-2.2.pc. This 2.2 series of the library can also
be parallel installed with the 2.0 and 1.2 series.
'make install' will also put the headers in different places: for the
library as installed for GTK-2 these are in
$prefix/include/c++-gtk-utils-2-2.2/c++-gtk-utils, for GTK-3 in
$prefix/include/c++-gtk-utils-3-2.2/c++-gtk-utils and for GTK-4 in
$prefix/include/c++-gtk-utils-4-2.2/c++-gtk-utils. The reason for
this is that although the library headers themselves are at present
identical in each case, the installed file cgu_config.h, which is
produced when running './configure' and its siblings, might be
different if different compilation options are chosen. This would
allow, for example, the GTK-2 binary to be compiled to use glib memory
slices, and the GTK-3 binary to be compiled to use the global
new/delete operators. This separation also gives more scope for
differentiation in the future, depending on how GTK-4 develops.
Although as mentioned above there are separate dynamic and static
library installations for GTK-2, GTK-3 and GTK-4 at the binary and
header level, they provide the same documentation (which is normally
located in $prefix/share/doc/c++-gtk-utils/2.2). This means that if
you run 'make uninstall' against, say, the tarball as configured for
GTK-2, but want to retain the documentation for future use for GTK-3
applications, it will be necessary to run 'make install' again against
the tarball configured for GTK-3. (So far as the distributions'
packaging management utilities are concerned, it might be better for a
single c++-gtk-utils package to have within it the binaries for both
GTK-2 and GTK-3 where that distribution provides both GTK-2 and GTK-3,
but if separately packaged the packaging utilities will handle the
situation as files common to two packages will not be deleted unless
both packages are removed.)
From version 2.0.15, the library can be built without GTK support
using the --without-gtk configuration option. If built with that
option, GTK is not required as a dependency: a build only requires
glib support.
If that option is chosen, there is no difference between configuring
with './configure-gtk2' (producing c++-gtk-utils-2-2.2.pc),
'./configure-gtk3' (producing c++-gtk-utils-3-2.2.pc) or
'./configure-gtk4' (producing c++-gtk-utils-4-2.2.pc): the end result
will be the same, namely that the following classes will not be
compiled into the library: Cgu::Application, Cgu::FilePrintDialog,
Cgu::FilePrintManager, Cgu::MainWidgetBase, Cgu::TextPrintManager and
Cgu::WinBase.
Note that the build system does not automatically choose the
--without-gtk option if an appropriate version of GTK-2, GTK-3 or
GTK-4 cannot be found. If GTK is not installed on the target machine,
the --without-gtk configuration option must be explicitly chosen.
Furthermore, the test suite will not be compiled if that configuration
option is chosen.
ABI COMPATABILITY
Every release in the 1.2, 2.0 and 2.2 series is ABI compatible with
earlier releases in the same series. None of the 1.2, 2.0 or 2.2
series is ABI compatible with a different series, but they are
parallel installable. This means that at any one time it is possible
to have 7 parallel installations of c++-gtk-utils: the 1.2 series for
GTK-2, the 1.2 series for GTK-3, the 2.0 series for GTK-2, the 2.0
series for GTK-3, the 2.2 series for GTK-2, the 2.2 series for GTK-3
and the 2.2 series for GTK-4.
DOCUMENTATION
Full html documentation is available in the docs/reference/html
directory of the tarball package, generated by doxygen. 'make
install' will install the html documentation by default in
${prefix}/share/doc/c++-gtk-utils/2.2/html. If the --docdir or
--htmldir options are passed to ./configure, then it will be installed
in ${docdir}/2.2/html or ${htmldir}/2.2/html.
The documentation is also available online at:
http://cxx-gtk-utils.sourceforge.net/index.html
LICENCE
The copyright to the library is held by me, Chris Vine.
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).'
CONTACTING THE AUTHOR
I can be contacted at: cvine -at- users -dot- sourceforge -dot- net.
