Tree [971484] v1_2 /
 History

HTTPS access


File Date Author Commit
 c++-gtk-utils 2016-11-25 Chris Vine Chris Vine [971484] Correct documentation about unbuffered channels...
 docs 2015-04-23 Chris Vine Chris Vine [c17c3d] Update Doxyfile.in for doxygen-1.8.9.1
 m4 2014-08-23 Chris Vine Chris Vine [d73e62] Update build system to automake-1.14.1 and gett...
 po 2016-11-23 Chris Vine Chris Vine [48064d] Bring to release level 1.2.42.1
 tests 2016-11-09 Chris Vine Chris Vine [84d3cb] Fix for gcc-4.6
 ABOUT-NLS 2012-08-10 Chris Vine Chris Vine [f7806e] Flatten repository tree
 AUTHORS 2012-08-10 Chris Vine Chris Vine [f7806e] Flatten repository tree
 BUGS 2012-08-10 Chris Vine Chris Vine [f7806e] Flatten repository tree
 COPYING 2012-08-10 Chris Vine Chris Vine [f7806e] Flatten repository tree
 ChangeLog 2016-11-25 Chris Vine Chris Vine [971484] Correct documentation about unbuffered channels...
 INSTALL 2013-06-10 Chris Vine Chris Vine [dae471] Update build system to automake-1.13.3
 Makefile.am 2014-08-23 Chris Vine Chris Vine [d73e62] Update build system to automake-1.14.1 and gett...
 Makefile.decl 2012-08-10 Chris Vine Chris Vine [f7806e] Flatten repository tree
 NEWS 2012-08-10 Chris Vine Chris Vine [f7806e] Flatten repository tree
 README 2015-01-31 Chris Vine Chris Vine [1d9cd4] Update README
 acinclude.m4 2016-07-25 Chris Vine Chris Vine [f50def] Adjust documentation about configuration for guile
 bootstrap-gtk2.sh 2014-08-23 Chris Vine Chris Vine [d73e62] Update build system to automake-1.14.1 and gett...
 bootstrap-gtk3.sh 2014-08-23 Chris Vine Chris Vine [d73e62] Update build system to automake-1.14.1 and gett...
 c++-gtk-utils-1.2.pc.in 2013-02-12 Chris Vine Chris Vine [5d4231] Revert "Add --without-cast-checks configuration...
 c++-gtk-utils-1.3.pc.in 2013-02-12 Chris Vine Chris Vine [5d4231] Revert "Add --without-cast-checks configuration...
 compile 2015-11-15 Chris Vine Chris Vine [484612] Make use of glib's unix fd implementation confi...
 config.guess 2013-06-10 Chris Vine Chris Vine [dae471] Update build system to automake-1.13.3
 config.rpath 2014-08-23 Chris Vine Chris Vine [d73e62] Update build system to automake-1.14.1 and gett...
 config.sub 2013-06-10 Chris Vine Chris Vine [dae471] Update build system to automake-1.13.3
 configure-gtk2.ac 2016-11-23 Chris Vine Chris Vine [48064d] Bring to release level 1.2.42.1
 configure-gtk3.ac 2016-11-23 Chris Vine Chris Vine [48064d] Bring to release level 1.2.42.1
 depcomp 2013-06-10 Chris Vine Chris Vine [dae471] Update build system to automake-1.13.3
 install-sh 2013-03-27 Chris Vine Chris Vine [e3454c] Update subsidiary files to automake-1.13.1
 ltmain.sh 2015-01-26 Chris Vine Chris Vine [12416d] Update libtool to version 2.4.4
 missing 2013-03-27 Chris Vine Chris Vine [011a3b] Update build system to automake-1.13.1

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 1.2 series of the library will compile with C++98/03.  Separate
2.0 and 2.2 series of the library are available for C++0x/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.

  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 static and non-static member functions,
  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

  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.

                             DEPENDENCIES

The library requires:

  glib >= 2.10.0

  gtk+-2.0 >= 2.10.0 or gtk+-3.0 >= 2.90.0 (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 which is C++-98 or later
  compliant.

  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.

                            INSTALLATION

To compile:

  ./configure (or ./configure-gtk2)
  make
  make install (as root)

In relation to use with GTK+2, or without GTK+ entirely, see further
under 'GTK versions' below.

To choose a prefix other than /usr/local, use the --prefix option with
./configure or ./configure-gtk2.  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).

Prior to version 1.2.0, the library only used namespaces for
modularity (providing namespaces for the Callback, MemFun, Thread and
Utf8 modules).  With version 1.2.0, the whole library (including those
module 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.

From version 1.2.10, callback objects can take two or three unbound
arguments instead of just one.  If this behaviour is not wanted, the
library can be configured with the --with-type-tuple-args=no (or
--without-type-tuple-args) option.

From version 1.2.12, the library provides operator==(), operator!=()
and operator<() 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 associative
containers, but only if the library is compiled with the
--with-smart-ptr-comp configuration option.  (The default is not to
provide these operators, so as to avoid double definition errors if
the library user code provides its own operators.)

                            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' is called, then the library will be prepared for
compilation against GTK+2.

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.

The compilation default can be changed to GTK+2 by calling
'./bootstrap-gtk2.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'
and for compilation against GTK+3 by calling '/configure-gtk3'.  It
will therefore not generally be necessary to call either
bootstrap-gtk2.sh or bootstrap-gtk3.sh.

The library as compiled for GTK+2 and for GTK+3 can be parallel
installed.  To configure a user program to link against the library as
installed for GTK+2, use c++-gtk-utils-1.2.pc, and to configure to
link against the library as installed for GTK+3, use
c++-gtk-utils-1.3.pc.  (The dynamically linkable libraries themselves
are separately installed in $prefix/lib as libcxx-gtk-utils.so.2 when
compiled for GTK+2, and as libcxx-gtk-utils-1.3.so.2 when compiled for
GTK+3.  It would have been more logical for these to be
libcxx-gtk-utils-1.2.so.2 and libcxx-gtk-utils-1.3.so.2 respectively,
but libcxx-gtk-utils.so.2 has been retained for the GTK+2 install in
order to maintain binary compatibility with earlier versions.  The
static libraries are libcxx-gtk-utils.a and libcxx-gtk-utils-1.3.a.)

'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-1.2/c++-gtk-utils, and for GTK+3 in
$prefix/include/c++-gtk-utils-1.3/c++-gtk-utils.  The reason for this
is that although the library headers themselves are at present
identical in either 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+3 develops.

The choice of c++-gtk-utils-1.3.pc for the version as installed for
GTK+3 does not imply that it is experimental.  That binary version
number has been chosen simply to distinguish it from an installation
for GTK+2, so that they can be parallel installed.

Although as mentioned above there are separate dynamic and static
library installations for GTK+2 and GTK+3 at the binary and header
level, they provide the same documentation (which is normally located
in $prefix/share/doc/c++-gtk-utils/1.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 1.2.28, 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-1.2.pc) and
'./configure-gtk3' (producing c++-gtk-utils-1.3.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 or GTK+3
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 6 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, and the 2.2 series for
GTK+3.

                            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/1.2/html.  If the --docdir or
--htmldir options are passed to ./configure, then it will be installed
in ${docdir}/1.2/html or ${htmldir}/1.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.

Get latest updates about Open Source Projects, Conferences and News.

Sign up for the SourceForge newsletter:





No, thanks