gtk-rs / pango

DEPRECATED, use https://github.com/gtk-rs/gtk-rs-core repository instead!

gtk3-rs

This project is UNMAINTAINED. Please take a look at gtk4-rs instead!

The gtk-rs organization aims to provide safe Rust binding over GObject-based libraries. You can find more about it on https://gtk-rs.org.

This repository contains all the "core" crates of the gtk-rs organization. For more information about each crate, please refer to their README.md file in their directory.

Minimum supported Rust version

Currently, the minimum supported Rust version is 1.70.0.

Documentation

• Examples
• The Rust API Stable / Development

Ecosystem

The gtk3-rs repository contains Rust crates for GTK 3. However there is a large ecosystem of GObject libraries and many of these libraries have Rust bindings based on the tooling included in gtk-rs. Of particular note:

• gtk-rs-core - bindings for some of the core libraries such as glib, gio, pango, graphene
• gstreamer-rs - bindings for the GStreamer media framework

Additionally, Rust bindings for various libraries are hosted on GNOME's GitLab instance and can be found at https://gitlab.gnome.org/World/Rust.

When using crates that are not part of the gtk-rs repository, you will need to be careful and ensure that they do not pull in incompatible versions of core crates like glib-rs.

Regenerating

To regenerate crates using gir, please use the generator.py file as follows:

$ python3 generator.py

If you didn't do so yet, please check out all the submodules before via

$ git submodule update --checkout

Development

This repository is mostly split into two branches: master and crate. master contains the not yet released code and is where new developments are happening. crate contains the last release source code and isn't supposed to be updated.

This repository is structured as follows:

- crate/
   |
   |-- README.md
   |-- Gir.toml
   |-- Cargo.toml
   |-- src/
   |-- sys/

The crate is a "top" directory (so "atk" or "gdk" in here for example). Each crate contains:

• README.md: explanations about the crate itself and eventually some details.
• Cargo.toml: descriptor of the crate, used by cargo and Rust.
• Gir.toml: configuration used by gir to generate most of the crates' code.
• src: the source code of the crate.
• sys: the 1:1 bindings of the C API.

The gir and gir-files top folders are not crates, but are git submodules which respectively contain the gir tool and the gir files used by the generator.

When running generator.py the tool will automatically update these git submodules and run the gir tool on the gir files to regenerate the code.

During development, it is useful to execute the generator with a different version of the gir tool or of the gir files, for instance to test if the code generation is successful before submitting a pull request to update one of the submodules. This can be done by specifying arguments to the generator script, for instance, to run the generator on a local copy of the gir files:

$ python3 generator.py --gir-files-directory ../gir-files/

See python3 generator.py --help for more details.

pango's Issues

need an enum for the PangoScale values

the original values are there:
https://developer.gnome.org/pango/stable/pango-Text-Attributes.html#PANGO-SCALE-X-LARGE:CAPS

They are #defined in pango. I believe they're needed to build a GtkTextTag with a specific size, as in the gtk3 demo:

  gtk_text_buffer_create_tag (buffer, "big",
                              /* points times the PANGO_SCALE factor */
                              "size", 20 * PANGO_SCALE, NULL);

  gtk_text_buffer_create_tag (buffer, "xx-small",
                              "scale", PANGO_SCALE_XX_SMALL, NULL);

  gtk_text_buffer_create_tag (buffer, "x-large",
                              "scale", PANGO_SCALE_X_LARGE, NULL);

I'm not really sure it should be an enum though, because the first example there seems to do arithmetic with the value (20*PANGO_SCALE).

Support pango_itemize API

This API is used to split text rendering into a series of runs, each of which contains a number of glyphs for a single font/style. I gave implementing it a shot, but I ran into some snags. Note that this is my first time attempting to use the gir generator, so I may very well be doing something stupid.

Generating the pango_itemize function seems to be mainly blocked by generating Pango.AttrIterator.

Pango.AttrIterator doesn't seem to have a free function, rather it has a destroy function instead. This causes the gir generator to panic because of missing memory management functions.

thread 'main' panicked at 'Missing memory management functions for Pango.AttrIterator {Copy: "pango_attr_iterator_copy"}', gir/src/codegen/record.rs:21

I implemented a hack in the generator to see how far I could get, but encountered some more errors as well.

When compiling with my hack (and a few more changes), code generation succeeded. When compiling I get some compile errors, mainly related to the FromGlib* and ToGlib* traits.

 Documenting pango v0.1.3 (file:///home/hansihe/git/pango)
error: no method named `to_glib_none_mut` found for type `std::option::Option<&auto::attr_iterator::AttrIterator>` in the current scope
   --> src/auto/functions.rs:169:171
    |
169 |         FromGlibPtrContainer::from_glib_full(ffi::pango_itemize(context.to_glib_none().0, text.to_glib_none().0, start_index, length, attrs.to_glib_none().0, cached_iter.to_glib_none_mut().0))
    |                                                                                                                                                                           ^^^^^^^^^^^^^^^^

error[E0277]: the trait bound `std::vec::Vec<item::Item>: glib::translate::FromGlibPtrContainer<_, *mut glib_sys::GList>` is not satisfied
   --> src/auto/functions.rs:169:9
    |
169 |         FromGlibPtrContainer::from_glib_full(ffi::pango_itemize(context.to_glib_none().0, text.to_glib_none().0, start_index, length, attrs.to_glib_none().0, cached_iter.to_glib_none_mut().0))
    |         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ the trait `glib::translate::FromGlibPtrContainer<_, *mut glib_sys::GList>` is not implemented for `std::vec::Vec<item::Item>`
    |
    = help: the following implementations were found:
              <std::vec::Vec<T> as glib::translate::FromGlibPtrContainer<P, *const P>>
              <std::vec::Vec<T> as glib::translate::FromGlibPtrContainer<P, *mut P>>
              <std::vec::Vec<T> as glib::translate::FromGlibPtrContainer<<T as glib::translate::GlibPtrDefault>::GlibType, *mut glib_sys::GSList>>
              <std::vec::Vec<T> as glib::translate::FromGlibPtrContainer<<T as glib::translate::GlibPtrDefault>::GlibType, *mut glib_sys::GList>>
              <std::vec::Vec<T> as glib::translate::FromGlibPtrContainer<<T as glib::translate::GlibPtrDefault>::GlibType, *const glib_sys::GList>>
    = note: required by `glib::translate::FromGlibPtrContainer::from_glib_full`

error: no method named `to_glib_none_mut` found for type `std::option::Option<&auto::attr_iterator::AttrIterator>` in the current scope
   --> src/auto/functions.rs:176:205
    |
176 |         FromGlibPtrContainer::from_glib_full(ffi::pango_itemize_with_base_dir(context.to_glib_none().0, base_dir.to_glib(), text.to_glib_none().0, start_index, length, attrs.to_glib_none().0, cached_iter.to_glib_none_mut().0))
    |                                                                                                                                                                                                             ^^^^^^^^^^^^^^^^

error[E0277]: the trait bound `std::vec::Vec<item::Item>: glib::translate::FromGlibPtrContainer<_, *mut glib_sys::GList>` is not satisfied
   --> src/auto/functions.rs:176:9
    |
176 |         FromGlibPtrContainer::from_glib_full(ffi::pango_itemize_with_base_dir(context.to_glib_none().0, base_dir.to_glib(), text.to_glib_none().0, start_index, length, attrs.to_glib_none().0, cached_iter.to_glib_none_mut().0))
    |         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ the trait `glib::translate::FromGlibPtrContainer<_, *mut glib_sys::GList>` is not implemented for `std::vec::Vec<item::Item>`
    |
    = help: the following implementations were found:
              <std::vec::Vec<T> as glib::translate::FromGlibPtrContainer<P, *const P>>
              <std::vec::Vec<T> as glib::translate::FromGlibPtrContainer<P, *mut P>>
              <std::vec::Vec<T> as glib::translate::FromGlibPtrContainer<<T as glib::translate::GlibPtrDefault>::GlibType, *mut glib_sys::GSList>>
              <std::vec::Vec<T> as glib::translate::FromGlibPtrContainer<<T as glib::translate::GlibPtrDefault>::GlibType, *mut glib_sys::GList>>
              <std::vec::Vec<T> as glib::translate::FromGlibPtrContainer<<T as glib::translate::GlibPtrDefault>::GlibType, *const glib_sys::GList>>
    = note: required by `glib::translate::FromGlibPtrContainer::from_glib_full`

error: no method named `to_glib_none` found for type `&[&item::Item]` in the current scope
   --> src/auto/functions.rs:250:85
    |
250 |         FromGlibPtrContainer::from_glib_full(ffi::pango_reorder_items(logical_items.to_glib_none().0))
    |                                                                                     ^^^^^^^^^^^^
    |
    = note: the method `to_glib_none` exists but the following trait bounds were not satisfied: `&item::Item : glib::translate::ToGlibPtr<_>`, `&item::Item : glib::translate::GlibPtrDefault`, `&item::Item : glib::translate::ToGlibPtr<_>`, `item::Item : glib::translate::GlibPtrDefault`, `item::Item : glib::translate::GlibPtrDefault`, `&item::Item : glib::translate::GlibPtrDefault`, `&item::Item : glib::translate::ToGlibPtr<_>`, `item::Item : glib::translate::GlibPtrDefault`, `item::Item : glib::translate::GlibPtrDefault`, `[&item::Item] : glib::translate::ToGlibPtr<_>`, `&item::Item : glib::translate::ToGlibPtr<_>`, `&item::Item : glib::translate::GlibPtrDefault`, `&item::Item : glib::translate::ToGlibPtr<_>`, `item::Item : glib::translate::GlibPtrDefault`, `item::Item : glib::translate::GlibPtrDefault`, `&item::Item : glib::translate::GlibPtrDefault`, `&item::Item : glib::translate::ToGlibPtr<_>`, `item::Item : glib::translate::GlibPtrDefault`, `item::Item : glib::translate::GlibPtrDefault`

error[E0277]: the trait bound `std::vec::Vec<item::Item>: glib::translate::FromGlibPtrContainer<_, *mut glib_sys::GList>` is not satisfied
   --> src/auto/functions.rs:250:9
    |
250 |         FromGlibPtrContainer::from_glib_full(ffi::pango_reorder_items(logical_items.to_glib_none().0))
    |         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ the trait `glib::translate::FromGlibPtrContainer<_, *mut glib_sys::GList>` is not implemented for `std::vec::Vec<item::Item>`
    |
    = help: the following implementations were found:
              <std::vec::Vec<T> as glib::translate::FromGlibPtrContainer<P, *const P>>
              <std::vec::Vec<T> as glib::translate::FromGlibPtrContainer<P, *mut P>>
              <std::vec::Vec<T> as glib::translate::FromGlibPtrContainer<<T as glib::translate::GlibPtrDefault>::GlibType, *mut glib_sys::GSList>>
              <std::vec::Vec<T> as glib::translate::FromGlibPtrContainer<<T as glib::translate::GlibPtrDefault>::GlibType, *mut glib_sys::GList>>
              <std::vec::Vec<T> as glib::translate::FromGlibPtrContainer<<T as glib::translate::GlibPtrDefault>::GlibType, *const glib_sys::GList>>
    = note: required by `glib::translate::FromGlibPtrContainer::from_glib_full`

error: Compilation failed, aborting rustdoc

error: Could not document `pango`.

To learn more, run the command again with --verbose.

Any ideas where I should go from here?

Missing bindings for PangoGravity functions

pango_gravity_to_rotation doesn't have a binding; this one should just look like a method.

The following are missing bindings, too, but they return a PangoGravity: pango_gravity_get_for_matrix, pango_gravity_get_for_script, pango_gravity_get_for_script_and_width.

Update pango bindings

Pango 1.44 has been around since end July, so would be good to get updated bindings.

Does not include cairo backend rendering.

pango/pangocairo.h includes a number of functions for rendering text with pango to cairo surfaces. Rust bindings for these functions are missing from pango/pango::ffi and sys/pango-sys.

Incorrect implementation of Layout::xy_to_index

pango_layout_xy_to_index returning FALSE does not mean index_ and trailing are junk values. In fact, they are very useful (example: click outside the text and see the output).

Please make the FFI generation to allow returning out values along with the returned boolean in cases like these.

Remove the Option return type for all types creation

Remove the Option return type for all types creation and replace it by an assert or something like it.

Why does Layout::set_text need a length argument?

Can't the length be calculated within Layout::set_text?

Add text style attributes support

We need at least:

• pango_attr_list_new
• pango_attr_list_insert
• pango_layout_set_attributes

PangoAttribute support

Looks like Text Attributes doesn't implemented at all. Does it easily implemented?

Personally, I need only pango_attr_underline_new, pango_attr_letter_spacing_new and pango_attr_strikethrough_new.

Pango::Language::get_sample_string() SIGSEGVing

Triggered by the lastest commit on https://github.com/Cogitri/gxi/tree/better-font-metrics-detection :

Cogitri/Tau@ef3249a

Environment:

x86_64 Alpine Linux Edge (musl)
Compiled with Rust 1.35.0beta3 x86_64-unknown-linux-musl
GTK+3.0 3.24.8
Pango 1.42.4
gtk-rs git master

The SIGSEGV occurs in glib::GString::Drop, so I guess it tries to free the GString even though https://gtk-rs.org/docs/src/pango/language.rs.html#221 tells us not to?

Relicense under dual MIT/Apache-2.0

This issue was automatically generated. Feel free to close without ceremony if
you do not agree with re-licensing or if it is not possible for other reasons.
Respond to @cmr with any questions or concerns, or pop over to
#rust-offtopic on IRC to discuss.

You're receiving this because someone (perhaps the project maintainer)
published a crates.io package with the license as "MIT" xor "Apache-2.0" and
the repository field pointing here.

TL;DR the Rust ecosystem is largely Apache-2.0. Being available under that
license is good for interoperation. The MIT license as an add-on can be nice
for GPLv2 projects to use your code.

Why?

The MIT license requires reproducing countless copies of the same copyright
header with different names in the copyright field, for every MIT library in
use. The Apache license does not have this drawback. However, this is not the
primary motivation for me creating these issues. The Apache license also has
protections from patent trolls and an explicit contribution licensing clause.
However, the Apache license is incompatible with GPLv2. This is why Rust is
dual-licensed as MIT/Apache (the "primary" license being Apache, MIT only for
GPLv2 compat), and doing so would be wise for this project. This also makes
this crate suitable for inclusion and unrestricted sharing in the Rust
standard distribution and other projects using dual MIT/Apache, such as my
personal ulterior motive, the Robigalia project.

Some ask, "Does this really apply to binary redistributions? Does MIT really
require reproducing the whole thing?" I'm not a lawyer, and I can't give legal
advice, but some Google Android apps include open source attributions using
this interpretation. Others also agree with
it.
But, again, the copyright notice redistribution is not the primary motivation
for the dual-licensing. It's stronger protections to licensees and better
interoperation with the wider Rust ecosystem.

How?

To do this, get explicit approval from each contributor of copyrightable work
(as not all contributions qualify for copyright, due to not being a "creative
work", e.g. a typo fix) and then add the following to your README:

## License

Licensed under either of

 * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
 * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)

at your option.

### Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any
additional terms or conditions.

and in your license headers, if you have them, use the following boilerplate
(based on that used in Rust):

// Copyright 2016 pango Developers
//
// Licensed under the Apache License, Version 2.0, <LICENSE-APACHE or
// http://apache.org/licenses/LICENSE-2.0> or the MIT license <LICENSE-MIT or
// http://opensource.org/licenses/MIT>, at your option. This file may not be
// copied, modified, or distributed except according to those terms.

It's commonly asked whether license headers are required. I'm not comfortable
making an official recommendation either way, but the Apache license
recommends it in their appendix on how to use the license.

Be sure to add the relevant LICENSE-{MIT,APACHE} files. You can copy these
from the Rust repo for a plain-text
version.

And don't forget to update the license metadata in your Cargo.toml to:

license = "MIT OR Apache-2.0"

I'll be going through projects which agree to be relicensed and have approval
by the necessary contributors and doing this changes, so feel free to leave
the heavy lifting to me!

Contributor checkoff

To agree to relicensing, comment with :

I license past and future contributions under the dual MIT/Apache-2.0 license, allowing licensees to chose either at their option.

Or, if you're a contributor, you can check the box in this repo next to your
name. My scripts will pick this exact phrase up and check your checkbox, but
I'll come through and manually review this issue later as well.

• @Blei
• @GuillaumeGomez
• @SimonSapin
• @TobiasBales
• @bpbp-boop
• @briankropf
• @buster
• @dndanik
• @frewsxcv
• @gekola
• @gkoz
• @gsingh93
• @jeremyletang
• @jgillich
• @kennytm
• @mathijshenquet
• @oakes
• @osa1
• @ptersilie
• @steveklabnik
• @zploskey