cairomm is a C++ wrapper for the cairo graphics library. It offers all the power of cairo with an interface familiar to C++ developers, including use of the C++ Standard Library where it makes sense.
Status
cairomm wraps most relevant parts of the cairo API and is API/ABI-stable. cairomm is used by gtkmm since 2.10.
There are two series of cairomm releases, each with its own stable API/ABI. Releases up to 1.14.z (z is any integer) belong to the cairomm-1.0 ABI series. They are used by gtkmm-2.4 and gtkmm-3.0. cairomm 1.16.0 and higher-numbered releases belong to the cairomm-1.16 ABI series. They are used by gtkmm-4.0.
Download
You can download tarballs with released versions of cairomm from the cairo release area.
Git Repository
If you want bleeding-edge code, (or if you want to help out with development of cairomm), you can check out cairomm from git, which you can also browse online.
Anybody can check out the latest source code anonymously with the following command:
git clone https://gitlab.freedesktop.org/cairo/cairomm.git
You can commit changes to your local repository but will not be able to push them to the central repository.
If you are a developer with a freedesktop.org account and would like to be able to push your changes to the central repository, you should use the following command to check out the latest source code (notice the lack of the https:// protocol prefix and the ':' after the domain name):
git clone git@gitlab.freedesktop.org:cairo/cairomm.git
This will use ssh to perform the checkout and will require you to have a freedesktop.org account.
For some basic information on using git, see the "Using Git" section below.
Documentation
There is API documentation available which can be browsed online and is also included in the tarball releases. In some cases, you may wish to refer to the C cairo API documentation as well.
In addition to the API documentation, there are several small example programs which ship with cairomm and demonstrate some of the basic functionality. These examples are in the examples/ directory of the release tarball or can be browsed online.
There is also some tutorial-like documentation available in the gtkmm manual. The Drawing Area chapter introduces some basic cairomm drawing concepts. Although the documentation is about using cairomm with gtkmm, most of the concepts apply whether you're using gtkmm or not. In addition, you may find it helpful to reference the C cairo tutorial. Most of the concepts will translate directly from the C API to the C++ API with very few changes.
License
cairomm is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
Contact
For questions or to contact the developers, please use the cairo mailing list.
Use GitLab issues to submit cairomm bugs/issues.
Using Git
Git allows you to set your name and email so your commits are properly attributed. You can do so as follows (using your real name and email address, of course):
git config --global user.name "John Doe"
git config --global user.email john.doe@domain.com
You can update a local repository by pulling the changes from the central repository with the command:
git pull
To create and submit patches
When you've made some changes, you can commit them to your local repository with the command:
git commit -a -m "Commit message"
The commit message should be in the style of the existing commit messages. Try to mention what you changed in each file and to mention the overall aim of your changes, including any relevant GitLab issue number.
If you don't have a developer account (and thus can't push directly to the central repository), but would like to have some of your local changes incorporated into the central repository, you can create a patch with the following command:
git format-patch origin
# this will spit out a separate diff for each commit as a file named
# 0001-description-of-first-commit.txt
# 0002-description-of-second-commit.txt
You can then open an issue and attach your patch so someone with a developer account can apply it. If you want to generate one big patch between your local repository and the central repository, even if you have made multiple local commits, you can do so as follows:
git pull # make sure your repository is up-to-date
git diff origin HEAD > my-changes.patch
If you have write access
After you've made one or more commits to your local repository and you want to push them out to the central repository (if your repository was checked out with the developer command above), you can do so with the following command:
git push origin HEAD
If you want to have your commits reviewed by other developers before you push them to the master branch, push them to a temporary git branch and open a merge request.